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This publication is intended for catalog administrators and VSAM 
system programmers. It contains reference information about the 
access method services commands used to manipulate VSAM catalogs 
and VSAM data sets. 

This book gives the format/ a brief description/ and examples of 
each access method services command used with VSAM catalogs and 
the objects cataloged in them. This book is meant to be a 
companion to MlS£E^ t jfc.ad..^ 

QU3jA & > GC26-4151, and 

* GC26-4138. 

For information on the use of commands related to VSAM catalog 
format and structure, see Qaial . For 
information on the use of commands related to VSAM data set 
format and structure, see V SA M. A .d mi D. i jS.t.t:RtA.O.n..Gyj. d ,S. 


O RG ANIZ A T I O N 


• Chapter 1, "Guide to Access Method Services" on page 1, 
summarizes the access method services functions and the 
commands used to perform them. 

• Chapter 2, "Introduction" on page 3, provides an overview of 
access method services, including command syntax 
considerations, dynamic allocation, and JCL for data set and 
volume identification, and the use of the time sharing 
option (TSO) and the IBM 3850 Mass Storage System with VSAM 
and access method services. Everyone who intends to use 
access method services should first read this chapter. 

• Chapter 3, "Controlling Command Execution" on page 21, 
describes the use of the IF-THEN-ELSE, SET, and PARM 
commands to control command execution and to specify 
diagnostic aids and printed-output options. 

• Chapter 4, "Functional Command Format" on page 29, lists the 
access method services commands and their format, describes 
the required and optional parameters, and lists their 
abbreviations. Examples at the end of each command section 
show how the commands and their parameters are used. 

• Appendix A, "Interpreting LISTCAT Output Listings," shows 
the output keywords and the field names associated with each 
type of catalog entry, and supplies listings for LISTCAT and 
their interpretation. 

• Appendix B, "Interpreting LISTCRA Output Listings," shows 
the information necessary to interpret the listings for a 
recoverable catalog. 

• Appendix C, "Sample Output from CHKLIST," shows the format 
and gives an explanation of the output for CHKLIST. 

• Appendix D, "Caution for JCL DD Parameters," gives a list of 
some JCL DD parameters to be used with caution. 

• Appendix E, "Invoking Access Method Services from a Problem 
Program," gives an example of how to use the access method 
services commands in a user program. 

• Appendix F, "Command Reference Summary," shows the format of 
each access method services command, and its parameters, 
abbreviations, and defaults. The commands are grouped 
together to allow you to remove these pages and use them as 
a quick-reference guide. 
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• "Glossary 11 defines terms relevant to access method services, 

VSAM, VSAM data sets, and VSAM catalogs. 

J 

PREREQUISITE KNOWLEDGE 

Readers of this book are presumed to have a background in 
programming, including: 

• Job control language 

• VSAM data administration 

• Catalog administration 


REQU I R i.BJP. MR tt IC AIIP N . S . 

You should be familiar with the information presented in the 

following publications: 

• M-V-§illEx_t,. e nd e.d_A,r c h i te c t ur_ e „ Xa taX^ , 

GC26-4138, describes the administration of tasks for 
catalogs and how to use the access method services commands 
to manipulate catalogs, and the objects cataloged in them. 

• MVS/Extended Architecture JCL User's Guide , GC28-1351, 

• MS^£x±e nd Mj ^h ilecjfcure J.. C UB e ferejnce, GC28-1352, 

describes the JCL parameters referred to in this 
publication. 

• MVS/Extended Architecture Message Library: System Messages 
(Volumes 1 and 2), GC28-1376 and GC28-1377, provides a 
complete listing of the messages issued by access method 
services. 

• Iiyj5£E>£t,eri i d^^ _A.dniin ^ ^ _.UtjJL i tj . es y 

GC26-4150, describes the utility programs available for use 
with non-VSAM data sets. 

• . M VS_/.Ej%t.en^^ AM_Admi. D js ,t ra t ipn ; , „ _,Ma crQ 

Instruction Reference , GC26-4152, provides information on 
macro instructions used to process VSAM data sets. 

• MS v jExte n d e d_ A r c hltectujr e... V S A .fj_ A d mj p i s tr.a t ion_Gul.de, 
GC26-4151, provides information on creating and processing 
VSAM data sets, backup and recovery, and various options 
affecting performance. 
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Within the text, references are made to the publications listed 
below: 


Short Title 

Publication Title 

Order Number 

Access Method 
Services Logic 

MVS/Extended Architecture 
Access Method Services 

Loaic 

LY26-3953 

and 

LY26-3997 

Cache Device 
Administration 

MVS/Extended Architecture 

C.ache Re.yjL.ce_Admin_i_s±ration 

GC26-4137 

Catalog 

Administration 

Guide 

MVS/Extended Architecture 
Cataloa Administration 

Guide 

GC26-4138 


,4 ' 
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Short Title 


Diagnosis Guide 


Checkpoint/ 
Restart User's 
Guide 


Data 

Administration 

Guide 


Introduction to 
the IBM 3850 
Mass Storage 
System 


JCL User's 
Guide 


JCL Reference 


OS/VS Mass 
Storage System 
Services: 
Reference 
Information 


RACF Command 

Language 

Reference 


RACF General 

Information 

Manual 


System-Data 

Administration 


System 

Generation 


System Macros 
and Facilities 


System Messages 


TSO Command 

Language 

Reference 


TSO Terminal 
User's Guide 


Publication Title 



Version 3 


MVS/Extended Architecture 
Cfaeck&gj pt/ Re s t art .U s er_V s 
Guide 



OS/VS Mass Storage System 



esource Access Control 




System-Data Administrate© 



Volumes 1 and 2 


MVS/Extended Architecture 
TSO Command Language 
Reference (0S/VS2 TSO 
Command Language Reference, 
as updated by Supplement 
SD23-0259 for MVS/XA) 


(as updated by Supplement 
SD23-0263 for TSQ/E) 


Order Number 


LY27-9550 


GC26-4139 


GC26-4140 


GA32-0028 


GC28-1351 


GC28-1352 


GC35-0017 


SC28-0733 


GC28-0722 


GC26-4149 


GC26-4148 


GC28-1150 

and 

GC28-1151 


GC28-1376 

and 

GC28-1377 


GC28-0646 


GC28-127 4 
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A uniform system of notation describes the format of access 
method services commands. This notation is not part of the 
language; it merely provides a basis for describing the 
structure of the commands. 


The command format illustrations in this book use the following 
conventions : 


• Brackets C ] indicate optional parameters. 

• Braces { > indicate a choice of entry; unless a default is 
indicated, you must choose one of the entries. 

• Items separated by a vertical bar (|) represent alternative 
items. No more than one of the items may be selected. 

• An ellipsis (...) indicates that multiple entries of the 
type immediately preceding the ellipsis are allowed. 

• Other punctuation (parentheses, commas, etc.) must be 
entered as shown. 

• BOLDFACE type indicates the exact characters to be entered. 
Such items must be entered exactly as illustrated (in 
uppercase, except in TSO). 

• LQM^n£.as.^.-M. n . d ALSJg-Q.r^,d type specifies fields to be supplied 
by the user. 

• BOLDFACE UNDERSCORED type indicates a default option. If 
the parameter is omitted, the underscored boldface value is 
assumed. 

• A 1 1 in the command format indicates a blank (an empty 

space) must be present before the next parameter. 
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SUMMARY OFCHANGES 


| R E L EA SE 

| SERVICE CHANGES 

| Minor technical changes have been made. 

B aeAS E- A JLL,j J . U Mg,lg8Ct 


NEW PROGRAMMING SUPPORT 

The EXAMINE command allows the user to analyze and report on the 
structural consistency of the index component and/or data 
component of a key-sequenced data set (KSDS) cluster. It is 
described in ’’Chapter 4. Functional Command Format" and in 
"Appendix F. Command Reference Summary." 

Information has been added to the DEFINE and DELETE commands fo 
non-VSAM data sets to reflect the RACF ERASE attribute availabl 
in RACF Version 1, Release 7. 


SERVICE CHANGES 


The first four sections of this manual have been reorganized. 
Minor technical changes have been made. 


BElr EAS E-I Jb, A RB I L12 85 

NEW DEVICE SUPPORT 


Selected examples in DEFINE NON VSAM and IMPORT CONNECT , a 
section of the required parameters for DEFINE PAGESPACE, and the 
Device Type Translate Table shown in Appendix A have been 
updated to reflect 3380 support. 


VERSION 2 PUBLICATIONS 

The Preface includes new order numbers for Version 2. 
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Figure 1 is a list of tasks that access method services commands 
can be used to perform. The left column shows tasks that you 
might want to perform. The middle column further describes the 
tasks. The right column shows the commands that can be used to 
perform each task. 



Task 

Description 

Alter 

attributes in catalog entries 

Attach 

user catalog to the master catalog 

Backup 

VSAM catalog 

VSAM data set 
non-VSAM data set 

Build 

alternate index 

Catalog 

VSAM data set 

VSAM data set with alternate 
index 


non-VSAM data set 
generation data group 

Connect 

user catalog to a master catalog 
or another user catalog 

OS CVOL to a master catalog 

Convert 

non-VSAM data set to VSAM format 
VSAM data set to SAM format 

OS CVOL entries to VSAM 
catalog entries 

Copy 

data set or catalog 


Define VSAM catalog 

alias for a non-VSAM data set 
alias for a user catalog 
alias for a VSAM data set 
alternate index 

relationship between an alternate 
index and its base cluster 
generation data group 
page space 
swap data set 
VSAM data set 
VSAM data space 
catalog entry for a non-VSAM 
data set 

Figure 1 (Part 1 of 2). Tasks and Commands 


Command 

ALTER 

IMPORT CONNECT 
REPRO 

EXPORT or REPRO 
REPRO 

DEFINE ALTERNATEINDEX and 
BLDINDEX 

DEFINE CLUSTER 
DEFINE CLUSTER and 
ALTERNATEINDEX 

DEFINE NONVSAM 

DEFINE GENERATIONDATAGROUP 


IMPORT CONNECT 
DEFINE NONVSAM 

REPRO 

REPRO 

CNVTCAT 

REPRO 

DEFINE USERCATALOG 
DEFINE ALIAS 
DEFINE ALIAS 
DEFINE PATH 

DEFINE ALTERNATEINDEX and 
BLDINDEX 

DEFINE PATH 

DEFINE GENERATIONDATAGROUP 
DEFINE PAGESPACE 
DEFINE PAGESPACE 
DEFINE CLUSTER 
DEFINE SPACE 

DEFINE NONVSAM 
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Task 

Description 

Command 

Delete 

user catalog 
alias 

VSAM data spaces and data sets 
alternate index and its paths 
path 

any type of catalog entry 

VSAM data set 

VSAM data space 
generation data group 
non-VSAM data set 
page space 

DELETE USERCATALOG 

DELETE ALIAS 

ALTER REMOVEVOLUMES 

DELETE ALTERNATEINDEX 
DELETE PATH 

DELETE 

DELETE CLUSTER 

DELETE SPACE 

DELETE GENERATIQNDATAGROUP 
DELETE NONVSAM 

DELETE PAGESPACE 

Disconnect 

user catalog 

EXPORT DISCONNECT 

Export 

user catalog 

VSAM data set 

EXPORT DISCONNECT 

EXPORT or EXPORTRA 

Import 

user catalog 

VSAM data set 

IMPORT CONNECT 

IMPORT or IMPORTRA 

Inspect 

a key-sequenced data set (KSDS) 
cluster 

EXAMINE 

List 

password 

data set's contents 
catalog's contents 

contents of a catalog or of a catalog 
entry (formatted) 

contents of a catalog recovery area 
tapes mounted at a checkpoint 

LISTCAT 

PRINT 

PRINT 

LISTCAT 

LISTCRA 

CHKLIST 

Load 

records into a data set 
alternate index 

REPRO 

BLDINDEX 

Move 

catalog to another system 

VSAM data set to another system 
non-VSAM data set to another system 

EXPORT DISCONNECT and 
IMPORT CONNECT 
EXPORT/IMPORT 

REPRO 

Print 

data set 

PRINT 

Recover 

from a processing-program failure 
from a catalog failure 

VERIFY 

LISTCRA 

EXPORTRA 

IMPORTRA and 

RESETCAT 

Rename 

data set 

ALTER 

Restore 

data set's end-of-file information 
catalog entry and/or the contents 
of its object 

data set from a portable copy 

VERIFY 

EXPORTRA/IMPORTRA or 
RESETCAT 

IMPORT 

Uncatalog 

data set 

DELETE 

Unload 

data set or catalog 

REPRO 

Verify 

VSAM data set's end-of-file 
indicators 

VERIFY 


Figure 1 (Part 2 of 2) . Tasks and Commands 
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Access method services is a service program used with the 
virtual storage access method (VSAM) to establish and maintain 
catalogs and data sets. If you plan to use VSAM, or if you are 
responsible for maintaining the system catalog, you must use 
access method services commands. 

There are two types of access method services commands: 
functional commands that are used to request the actual work 
Cfor example, defining a data set or listing a catalog) and 
modal commands that allow the conditional execution of 
functional commands. The access method services modal commands 
are presented under Chapter 3, "Controlling Command Execution” 
on page 21. The access method services functional commands and 
their parameters are listed in alphabetic order under 
Chapter 4, "Functional Command Format” on page 29. Examples of 
the use of each command are included. TSO users are allowed to 
use only the functional commands. 

This is a reference book only. See &ala Lqj^ a J3 Mi d<3 

and V MM, Ad m infor information on the tasks 
performed using access method services commands. 


All access method services commands have this general structure: 

command parameAans. ••• t.terminator3 


Commands 


COMMAND specifies the type of service requested. The parameters 
further describe the service requested. The terminator 
indicates the end of the command statement. 

Commands can begin at or to the right of the left margin. For 
batch processing jobs, the default margins are 2 and 72. 

Commands are separated from their parameters by one or more 
separators (blanks, commas, or comments). For some parameters, 
parentheses are specified as separators. Comments are strings 
of characters surrounded by a /* and an */. Comments may 
contain any characters except an f x/*. 

Many of the commands and keyword parameters may be abbreviated. 
The abbreviations allowed are listed in the description of each 
command and in Appendix F, "Command Reference Summary" on 
page 326. Keyword parameters in plural form may also be coded 
in the singular form. Restrictions that apply to abbreviations 
under TSO are described under "From a TSO Terminal" on page 13. 


Positional and Keyword Parameters 

A parameter may either be a positional parameter or a keyword 
parameter. Positional parameters must always appear first in a 
parameter set. In access method services, positional parameters 
are never optional. 
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For example# in* 


DELETE - 

USERCAT - 

USERCAT is a positional parameter that specifies the entryname 
to be deleted. 

A keyword parameter is a specific character string# which may 
have a value following it. For example# in: 

VOLUME C25DATA) 

VOLUME is a keyword that indicates that the value 25DATA is a 
volume serial number. 

A keyword parameter may have a set of subparameters. 
Subparameters follow the same rules as parameter sets in 
general. When the subparameters are positional# the first 
subparameter is always required. 

Positional parameters and subparameters sometimes consist of 
lists of items. Unless the list contains only one item# it must 
be enclosed in parentheses# which may be preceded and followed 
by blanks# commas# or comments. For example: 

DELETE(.enAnyoams [•••3) 

indicates that# if more than one entry is to be deleted# the 
list of entrynames must be enclosed in parentheses. However# if 
only one entryname is specified# the parentheses are not 
required. 

An item in a list can be a parameter set itself. Each such 
item# as well as the list of items# is enclosed in parentheses. 
Given: 

OBJECTS iim±nxna m newname Cnmnarall.»«1 

the following are valid: 

OBJECTSC - 

ENTRY1 NEWNAMECNEWNAME1)) 

OBJECTSC ~ 

(ENTRY1 NEWNAMECNEWNAME1)) - 
CENTRY2 NEWNAMEC NEWNAME2))) 

In the first case# only one entry is to be renamed. The 
entryname and its new name are enclosed in parentheses. 

In the second case# each entryname and its new name are enclosed 
in parentheses and the entire list is enclosed in parentheses. 

All parameters and subparameters must be separated from each 
other by one or more separators (commas# blanks# or comments). 
There is one exception: Parameters that immediately follow a 
subparameter set that is enclosed in parentheses do not need to 
be separated from the closing parenthesis. 

A value cannot contain commas# semicolons# blanks# parentheses# 
or slashes unless the entire value is enclosed in single 
quotation marks. A single quotation mark in a field enclosed in 
single quotation marks must be coded as two single quotation 
marks. 

The values you specify in the parameters can be surrounded by 
separators. Some values can be longer than a single record. 

When a value is longer than a single record# you indicate that 
it is continued by coding a plus sign (+) followed only by 
blanks or a comment. The first nonseparator character found in 
a record following the plus sign is treated as a continuation of 
the value. 
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In some parameters it is necessary to specify a password 
following the name of a catalog entry or the name of a JCL DD 
statement. You do this by coding the name, a slash/ and the 
password. (Separators are allowed on either side of the slash.) 
For example: 

DELETE PAYROLL/CTLGPAY 

specifies the password CTLGPAY for the data set PAYROLL. 

When you specify a password following a name, you must remember 
the convention for entering commands. If you code: 

MYNAME/XWORDX/ 

MYNAME is treated as a name followed by the comment WORD. If 
you want XWORD*/ to be the password, you code either: 

MYNAME/'XWORDX/' 


or 


MYNAME/ XWORD*/ 

Notice that the second example contains a blank after the first 
slash that separates the name from the password. 


How to Code Subparameters 

The following coding conventions apply to the subparameters 

listed in this section: 

• When the subparameter contains a special character, enclose 
it in single quotation marks; for example, CODEC■XSECRETX 1 ). 

• When the subparameter contains a special character and a 
single quotation mark, code the embedded quotation mark as 
two single quotation marks; for example, VOLUMESC^ne*"S’). 

• When you code the subparameter in hexadecimal form, two 
hexadecimal characters represent one alphameric or special 
character. Because the character string will be right 
justified, you should use an even number of hexadecimal 
characters; for example, MASTERPWCX*E3D6D7 1 ) is the same as 
MASTERPW(TOP). 

• When the subparameter contains a lowercase alphabetic 
character, it will be folded to an uppercase alphabetic 
character. 

The subparameters most often referred to in this book are: 

alia sDi ajpje 

can contain 1 to 44 alphameric or national characters, and 
two special characters (the hyphen (-) and the 12-0 
overpunch (X f CO 1 )). 

Names that contain more than 8 characters must be segmented 
by periods; 1 to 8 characters may be specified between 
periods. 

The first character of any name or name segment must be 
either an alphabetic character or a national character. 


code 

can contain 1 to 8 alphameric or special characters. 


£.p, t . ryname . 

can contain 1 to 44 alphameric or national characters, and 
two special characters (the hyphen (-) and the 12-0 
overpunch (X'CO 1 )). 
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Names that contain more than 8 characters must be segmented 
by periods; 1 to 8 characters may be specified between 
periods. A name that is segmented by periods is called a 
qualified name. Each name segment is referred to as a 
qualifier. 

The first character of any name or name segment must be 
either an alphabetic character or a national character. 

For a partitioned data set, entryname must be specified in 
the format: pdsname(membername). Blank characters are not 
allowed between the left and right parentheses enclosing 
the membername, or between pdsname and the left 
parentheses. 

If you specify an entryname in the format 

entryname(modifier), and the entryname is not the name of a 
partitioned data set, only that portion of the name 
preceding the left parenthesis will be used. The modifier 
enclosed in parentheses will be ignored. 

e a try ppint 

can contain 1 to 8 alphameric or national characters, and 
two special characters (the hyphen (-) and the 12-0 
overpunch (X s CO 1 )). 

The first character of any name or name segment must be 
either an alphabetic character or a national character. 


can contain 1 to 44 alphameric or national characters, and 
two special characters (the hyphen (-) and the 12-0 
overpunch (X 1 CO 1 )). 

Names that contain more than 8 characters must be segmented 
by periods; 1 to 8 characters may be specified between 
periods. 

The first character of any name or name segment must be 
either an alphabetic character or a national character. 


flwaeni d 

can contain 1 to 8 EBCDIC characters. 


jeassMorri 

can contain 1 to 8 alphameric or special characters. 


m isna me () 

specifies the entryname for a partitioned data set. Blank 
characters are not allowed between the left and right 
parentheses enclosing the membername, or between pdsname 
and the left parenthesis. 


st ri ng 

can contain 1 to 255 EBCDIC characters. 


. YQ .l s .e r 

a volume serial number, can contain 1 to 6 alphameric, 
national, or special characters. 


Alphameric, National, and Special Characters 

The following is a list of alphameric, national, and special 
characters that are referred to throughout this book: 

• Alphameric characters: 

alphabetic characters A-Z 

numeric characters 0-9 
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• National characters 


at sign C93 
dollar sign [§] 
pound sign C#3 
• Special characters 
ampersand [&] 
asterisk [*3 
blank C ] 
braces [{ or >3 
brackets CC or 33 
comma [, 3 
equal sign 03 
hyphen C~3 

parenthesis C( or )3 
period C.3 
plus sign C+3 
semicolon [;3 
single quotation mark [ f 3 
slash C/3 


How to Continue Commands and Parameters 

Commands can be continued on several records or lines. Except 
for the last line/ each record or line must have a hyphen or a 
plus sign as the last nonblank character before or at the right 
margin. 

A hyphen indicates continuation of the command. A plus sign 
indicates continuation of the command and continuation of a 
value within the command. 

These two types of continuation are shown in the example below: 

DELETE ~ 

CENTRY1 - 
ENTRY2 - 
ENTR+ 

Y3) - 
NONVSAM 

A blank record or a record ending with a complete comment must 
end with a continuation mark when it appears in the middle of a 
command and when it precedes or follows the THEN and ELSE 
clauses of an IF command. 

• IF LASTCC = 0 - 
THEN - 
REPRO ... 

/^COMMENT WITH NO CONTINUATION MARK AFTER*/ 

ELSE ~ 

PRINT ... 

Because no continuation mark (hyphen) follows the comments/ a 
null command is assumed. The ELSE keyword will not match up 
with the THEN keyword. 
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Records ending with partial comments must always end with a 
continuation mark. Also/ remember that only blank characters 
may appear between a continuation mark and the end of the 
record. 

Note: The DO-END sequence does not require continuation 

characters. If continuation characters are used, they may be 
taken as a null command or cause unpredictable results. 


The Terminator 


The terminator indicates the end of the command. The terminator 
can be either a semicolon or the absence of a continuation mark. 

If you use the semicolon as the terminator/ it cannot be 
enclosed in quotation marks or embedded in a comment. 

Everything to the right of the semicolon is ignored. 

If there is information to the right of the semicolon that is 
continued to another record/ all the information/ including the 
continued information/ is ignored. 

For example/ if you code: 

PARM TEST (TRACE); PARM - 
GRAPHICS (CHAIN(TN))/*COMMENT*/ - 
PRINT ... 

REPRO .. . 

Characters following the semicolon terminator are ignored. 
Because there is a continuation mark (hyphen) at the end of the 
second record/ the PRINT command is also ignored. The first 
PARM command and the REPRO command are the only commands that 
are recognized. 


□T^N O . Q N 

Access method services commands require that both data sets and 
volumes be identified when they are used. A data set must be 
identified when it is accessed. A volume or volumes must be 
identified when VSAM accesses the volume table of contents 
(VTOC)/ allocates or releases space using OS/VS DADSM functions/ 
or accesses a catalog recovery area. (See Catalog 
Ad mi ,, n ±^tr a llQD^yide for information on this option.) 

A VSAM data set or volume can be identified through JCL or by 
the data set name or volume serial ntimber within the command 
that requires the data set or volume for its execution. If JCL 
is not used/ an attempt is made to dynamically allocate the data 
set or volume/ as required. 


DYNAMIC ALLOCATION 


To dynamically allocate a VSAM data set/ the data set name must 
exist and be cataloged. The catalog that contains the entry 
must be either a user catalog identified with a JOBCAT or 
STEPCAT DD statement/ a user catalog whose name or alias is the 
first qualifier of the qualified data set name/ or the master 
catalog. 

To dynamically allocate a non-VSAM data set/ the data set name 
must exist and must be cataloged. The catalog that contains the 
entry must be either a user catalog identified with a JOBCAT or 
STEPCAT DD statement/ a user catalog or OS CVOL whose name or 
alias is the first qualifier of the qualified data set name, or 
the master catalog. 

"X 

Access method services dynamically allocates VSAM and non-VSAM 

data sets with a disposition of OLD. \ v 
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When a user catalog is identified by name in an access method 
services command (using the CATALOG parameter) or when VSAM 
determines that a specific user catalog must be accessed/ an 
attempt is made to dynamically allocate it/ if it has not been 
identified with a JOBCAT or STEPCAT DD statement. 

In order to dynamically allocate a volume/ it must already be 
mounted as permanently resident or reserved. The PRIVATE and 
PUBLIC use attributes should be carefully considered when you 
mount a volume. 

JCL should be used for allocation with data sets that reside on 
Mass Storage System (MSS) volumes/ because MSS volumes are 
rarely mounted as permanently resident or reserved. A request 
to dynamically allocate a data set on MSS/ or an MSS volume/ may 
result in a nonzero return code from allocation. 


JCL DD STATEMENTS 


When a JCL DD statement is used to identify a data set/ the 

following information must be included on the DD statement. 

• The data set name. 

• The unit and volume serial number(s)/ if the data set is not 
cataloged. 

• The disposition. 

• For VSAM data sets/ the AMP= f AM0RG l parameter is required if 
the JCL also supplies unit and volume serial number 
information. 


For a VSAM Data Set 


The two DD statements shown below demonstrate two different 
methods by which you can describe and allocate a VSAM data set: 

//VSAMDS1 DD DSN=VSAM.DATA.SET1/DISP=0LD 
//VSAMDS2 DD DSN=VSAM. DATA .SET2/VOL=SER=VSER01/ 

// UNIT^DISK/DISP=OLD/AMP= 1 AMORG 1 

Access method services does not provide specific protection for 
data sets in a shared environment. Therefore/ you should 
specify DISP=QLD on the DD statement for any data set that could 
be accessed improperly in a shared environment. 

VSAM uses default buffering for VSAM data sets. The default is 
the buffer space value contained in the data set f s catalog 
entry. You may want to override this value using the BUFSP 
subparameter of the AMP parameter (see VSAM Administration Guide 
for information on this parameter). 


For a Volume 

To identify and allocate a volume/ the following information 
must be included: 

• The volume serial number 

• The disposition 

• The unit 

For example/ the DD statement shown below identifies and 
allocates volume VSER01: 

//VOLDD DD VOL=SER=VSER01,UNIT=DISK/DISP=OLD 

Concatenated DD statements are supported under circumstances 
explicitly specified in the remainder of this publication. 
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"Direct Allocation Using JOBCAT and STEPCAT DD Statements" on 
page 11 contains a description of the DD statements required for 
user catalogs. 


iiT\ 


For a Non-VSAM Data Set 

Methods of describing and allocating non-VSAM data sets are 
shown in the DD statements of the examples provided with the 
following commands: BLDINDEX, EXPORT, IMPORT, REPRO, 

PRINT,EXPORTRA, and IMPORTRA. 


For a Snap Dump 


If access method services encounters a condition that requires 
it to abort a job, it takes a snap dump of virtual storage. An 
AMSDUMP DD statement is required to obtain the snap dump; for 
example, 

//AMSDUMP DD SYS0UT=A 

If you do not supply an AMSDUMP DD statement and access method 
services encounters a condition requiring the job to be aborted, 
it produces only an abbreviated dump. 


For a Target Data Set 

The normal target data set for listing is SYSPRINT. The default 
parameters of this data set are: 

• Record format: VBA 

• Logical record length: 125, that is, 121+4 

• Block size: 629, that is, (5x(121+4))+4 

Print lines are 121 bytes in length. The first byte is the ANSI 
(American National Standards Institute) control character. The 
minimum specifiable LRECL is 121 (U-format records only). If a 
smaller size is specified, it is overridden to 121. 

It is possible to alter the above defaults through specification 
of the desired values in the DCB parameter of the SYSPRINT 
statement. The record format, however, cannot be specified as F 
or FB. If you do specify either one, it is changed to VBA. 


For an Alternate Target Data Set 

In several commands you have the option of specifying an 
alternate target data set for listing. If you do specify an 
alternate, you must specify DCB parameters in the referenced DD 
statement by using the attributes described above. 

When specifying an alternate target data set, you should not 
specify F or FB record formats. 

Note: JCL statements, system messages, and job statistics are 

written to the SYSPRINT output device, not to the alternate 
target data set. Appendix B, "Interpreting LISTCRA Output 
Listings" on page 301 shows an example of the use of an 
alternate target data set. 
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DIRECT ALLOCATION USING JOBCAT AND STEPCAT DD STATEMENTS 




User catalogs can be allocated directly by using a JOBCAT or 
STEPCAT DD statement. 


You can specify a catalog that is to be available for use only 
with a job step, or that is to be available for the entire job. 
A STEPCAT DD statement identifies a catalog that is available 
for a single job step; a JOBCAT DD statement identifies a 
catalog that is available during the entire job. When both 
JOBCAT and STEPCAT catalogs are specified, the user catalog 
specified by STEPCAT is used for the job step. The JOBCAT and 
STEPCAT statements you code should be in the form: 


//JOBCAT DD DISP={OLD|SHRJ, 

// DSNAME=usercatname 


and 


//STEPCAT DD 
// 


DISP=(OLD|SHR }f 
DSNAME=usercatname 


Because the master catalog contains information about each user 
catalog, you do not need to specify the catalog f s volume and 
device information. 


You can specify more than one user catalog for a job or job 
step. To indicate another user catalog, follow the JOBCAT or 
STEPCAT DD statement with a concatenated DD statement—an 
unlabeled DD statement that specifies the name of another user 
catalog: 

//STEPCAT DD DISP=SHR,DSN=MGMTCAT1 
// DD DISP=SHR,DSN=MGMTCAT2 

Supplying a JOBCAT or STEPCAT DD statement to allocate the 
catalog is optional when: 

• Your job processes a user catalog (that is, when your 
sequence of access method services commands adds, modifies, 
lists, or deletes a catalog entry) 

• Your job includes a space allocation request directed toward 
a volume that contains VSAM data spaces (that is, a DEFINE 
SPACE or DELETE SPACE command) 

• Your job causes a VSAM data set to be opened and that data 
set is defined in a user catalog (that is, a REPRO or PRINT 
of a VSAM data set, a DELETE with the ERASE option, EXPORT, 
IMPORT, IMPORTRA, BLDINDEX, or VERIFY) 

For information on REPRO and JOBCAT/STEPCAT DD statements, 
see Catalog Administration Guide . 


Supplying a JOBCAT or STEPCAT DD statement to allocate the 
catalog is required when: 


• Your job causes the catalog to be opened as a data set (for 
example, using the PRINT command to print a catalog, using 
the LISTCRA command with the COMPARE option, or using the 
VERIFY command to restore end-of-file indicators of a user 
catalog). 

• Your job causes the scheduler allocation of the user catalog 
to be bypassed because unit and volume information was 
specified on the DD statement describing the VSAM data set 
defined in that user catalog. 
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Hhen you want to use an access method services function, you 
issue a command and specify its parameters. Your request is 
decoded, one command at a time, and the appropriate functional 
routines are then called to perform all services required by 
that command. 

There are three ways you can invoke the access method services 
program: 

• As a job or jobstep 

• From a TSO terminal 

• From within your own program 

You can execute the IDCAMS program and include the command and 
its parameters as input to the program. You can also call the 
IDCAMS program from within another program and pass the command 
and its parameters to the IDCAMS program. 

Time sharing option (TSO) users can execute access method 
services functional commands from the TSO terminal as though 
they were TSO commands. (See Appendix E, "Invoking Access 
Method Services from a Problem Program" on page 319, for 
information on invoking access method services.) 

For more details on the structure and operation of access method 
services, see Mgjj sg . M , fiJ ±LadLS.e r Y . iSiffi5..L fi fl i £« 


AS A JOB OR JOBSTEP 


You can use job control language (JCL) statements to invoke 
access method services. The examples that illustrate each 
command's use invoke access method services with JCL statements. 
You identify the access method services program with PGM=IDCAMS. 

//YOURJOB JOB YOUR INSTALLATION'S J0B=ACC0UNTING DATA 
//JOBCAT DD DSNAME=Y0UR.CATALOG,DISP=SHR 

//STEP1 EXEC PGM=IDCAMS 

//STEPCAT DD DSNAME=ANOTHER.CATALOG,DISP=SHR 
//SYSPRINT DD SYS0UT=A 

//SYSIN DD X 

(access method services commands and their parameters) 

/x 


• //YOURJOB is required. The JOB statement describes your job 
to the system. Your installation might require you to 
supply user identification, accounting, and authorization 
information with the JOB statement's parameters. 

• //JOBCAT is optional. The JOBCAT DD statement identifies a 
user catalog that can be used by each of the job's steps. 

Because the master catalog is always open and available to 
all jobs on the system, you should not identify it with a 
JOBCAT DD statement. 

• //STEP1 is required (that is, an EXEC statement is 
required). The EXEC statement invokes access method 
services to decode and process the input statements (that 
is, the access method services commands and parameters 
contained in the SYSIN data set). You can use the PARM 
operand of the EXEC statement to pass parameters to access 
method services. See the description of the PARM command in 
Chapter 3, "Controlling Command Execution" on page 21, for 

an explanation of the options you can specify. .. 

/ffl 

• //STEPCAT is optional. The STEPCAT DD statement identifies \ 
a user catalog that can be used when processing the jobstep. 

If user catalogs are identified with JOBCAT and STEPCAT DD 
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statements^ only the catalog(s) identified with the STEPCAT 
DD statement and the master catalog are used with the 
jobstep. Because the master catalog is always open and 
available to all jobs on the system/ you should not identify 
it with a STEPCAT DD statement. 

• //SYSPRINT is required. The SYSPRINT DD statement 
identifies the output device (usually a printer in a batch 
job) to which access method services sends messages and 
output information. (See "For a Target Data Set" on page 10 
for more details on how to describe an output device other 
than SYSOUT=A.) 

• //SYSIN is required. The SYSIN DD statement identifies the 
source of the input statements. An input statement is a 
functional or modal command and its parameters. When you 
code SYSIN DD x, you identify the immediately following 
statements as input. 

The last input statement may be followed by a delimiter 
statement that has "/X" in the first two columns. The 
restrictions that apply to all access method services commands 
are described in "How to Code Access Method Services Commands" 
on page 3. 


FROM A TSO TERMINAL 


TSO is a subsystem that provides conversational time sharing 
from remote terminals. You can use TSO with VSAM and access 
method services to* 

• Execute access method services commands 

• Execute a program to call access method services 

When you use TSO to process your data/ you can invoke access 
method services from your TSO terminal. Each time you issue an 
access method services command as a TSO command/ TSO builds the 
appropriate interface information and invokes access method 
services. 

You can issue one command at a time. Access method services 
processes the command completely before TSO allows you to 
continue processing. Except CHKLIST/ all the access method 
services functional commands referred to in this book are 
supported in a TSO environment. 

When TSO is used with access method services/ the following 
differences must be observed* 

• TSO allows the initial characters of a keyword to be 
supplied as an abbreviation of the keyword. The only 
restriction is that enough initial characters must be 
supplied to make the keyword unique. TRACKS/ for example/ 
could be abbreviated TR, TRA/ or TRAC/ because no other 
keyword within the same command can be abbreviated in the 
same way. 

Some abbreviations that are acceptable to access method 
services/ such as CYL/ CYLINDER/ REC/ RECORD/ cannot be used 
under TSO because the abbreviations do not contain enough 
initial characters to make the keyword unique. TSO cannot 
tell whether you mean CYLINDERS or CYLINDERFAULT when CYL or 
CYLINDER is used. Similarly/ abbreviations REC and RECORD 
are ambiguous; TSO does not know if you mean RECORDS or 
RECORDSIZE. 

• In addition/ the abbreviations described in the remainder of 
this publication (for example/ TRK for TRACKS) are 
acceptable to TSO. 

• When a parameters value consists of a list of one or more 
parenthesized parameter set s, the outer parentheses 
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surrounding the list are always required. For example, if 
lowkey and highkey form a parameter set that can be repeated 
several times, then the outer parentheses are required even 
when just one parameter set is specified; as follows: 

KEYWORDC(1owkey highkey)) 

• Under TSO, a volume serial number can consist of alphabetic, 
national, numeric, or special (hyphen only) characters; if 
any other characters are used, the volume serial number 
cannot be used as an entryname under TSO. 

• A name can be specified in quotation marks or not in 
quotation marks. Under TSO, however, a prefix (for example, 
the userid) is added to a name that is not in quotation 
marks. The prefix becomes the first qualifier in the name. 
If the name is a volume serial number (as it may be in the 
DELETE command, for example), enclose it in quotation marks; 
if you do not, a prefix is added to the volume serial 
number. 

• Under TSO, a password can be supplied with any entryname; 
the password is ignored if not required. 

Note: At a TSO terminal, the logon password is checked 

first, before the user is prompted to supply a password for 
a cluster. Checking the logon password counts as one 
attempt to obtain a password. If the user has not specified 
ATTEMPTS in the DEFINE command, only one attempt to supply 
the catalog's password is allowed because the default is 
two. 

• Under TSO, the user is prompted to complete a fully 
qualified name. The user is also prompted to supply 
required, but omitted, parameters. 

• The modal commands, used to control execution (IF-THEN-ELSE 
command sequence, DO-END command sequence, SET, and PARM), 
are not allowed under TSO. 

• Under TSO, the SYSPRINT data set is not used. The OUTFILE 
parameter may be used to specify a data set to receive the 
output procedure from access method services. 

For details about the format of a displayed catalog entry 
(resulting from a LISTCAT command) for a TSO user, see 
Appendix A, "Interpreting LISTCAT Output Listings" on page 256. 

Other TSO restrictions are noted with the descriptions of each 
appropriate parameter. 

For details about writing and executing programs and allocating 

data sets with TSO, see I SQ ^jemLaal..U s finlff- S Mlrifi and ISQ 

£s mmand I s n a m ge Jtefgjcfins. e * 


FROM A USER'S PROGRAM 

A processing program can invoke access method services with the 
ATTACH, LINK, LOAD, and CALL macros. Before the program issues 
the invoking macro, however, it must initialize the appropriate 
register and argument list contents. 

The contents of registers follow standard linkage conventions; 
that is, register 1 contains the address of the argument list, 
register 13 contains the address of a save area, register 14 
contains the address of the return point, and register 15 
contains the address of the entry point IDCAMS in access method 
services. 

The contents of the argument list are described in 
Appendix E, "Invoking Access Method Services from a Problem 
Program" on page 319. For information on manipulating sensitive 
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data in a secured environment, see "Authorized Program Facility" 
in fiatalftfl.Admi.niMn^li.p elGm id q . 


P.BPJ£R^E^QAIAkflCLALS£ 


You can specify the catalog to be searched or selected for an 
entry with the CATALOG parameters, or with a JOBCAT DD or 
STEPCAT DD statement. 


Order of Catalog Search for ALTER 

The order in which catalogs are searched when an entry is to be 
located for ALTER is: 

1. If a catalog is specified in the CATALOG parameter, only 
that catalog is searched. If the entry is not found, a "no 
entry found" error is returned to the user. 

2. Any user catalog(s) specified in the current job step with a 
STEPCAT DD statement is searched. If more than one catalog 
is specified for the job step, the catalogs are searched in 
order of concatenation. If the entry is found, no other 
catalog is searched. 

If a STEPCAT catalog is specified and the entry is not 
found, the JOBCAT catalog is not searched. The catalog 
search continues with step 3 below. 

If no STEPCAT catalog is specified for the job step, and a 
user catalog is specified for the current job with a JOBCAT 
DD statement, the JOBCAT catalogCs) is searched. If more 
than one catalog is specified for the job, the catalogs are 
searched in order of concatenation. If the entry is found, 
no other catalog is searched. Otherwise, 

3. If the entry is identified with a qualified entryname, and 
it is not of the generic form, and its first qualifier is 
the same as; 

• The name of a user catalog, or 

• The alias of a user catalog, or 

• The alias of an OS CVOL, 

the user catalog or OS CVOL so identified is searched. If 
the entry is found, no other catalog is searched. 

Otherwise, 

4. The master catalog is searched. If the entry is not found 
in any of the indicated catalogs, a "no entry found" error 
is returned to the user. 


Order of Catalog Selection for BLDINDEX 

The order in which catalogs are selected to contain work file 

entries is: 

1. If a catalog is specified with the CATALOG parameter, that 
catalog is selected to contain work file entries. 

2. Otherwise, the user catalog specified in the current job 
step (STEPCAT) or, if none is specified for the job step, 
the user catalog specified for the current job (JOBCAT) is 
selected to contain the work file entries. If more than one 
catalog is specified for the job step or job, the first 
STEPCAT or JOBCAT catalog is selected to contain the work 
file entries. 
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3. Otherwise, if the entries (data set name on the DD 
statement) are identified with qualified entrynames and the 
first qualifier is the same as: 

• The name of a user catalog, or 

• The alias of a user catalog, 

the user catalog so identified is selected to contain the 
work file entries. 

4. Otherwise, the master catalog is selected to contain the 
work file entries. 


Catalog Selection for CNVTCAT 

The target catalog selected to receive the converted entries is 
the catalog specified in the OUTFILE, OUTDATASET, or CATALOG 
parameter. 

The source catalog, the catalog that contains the entries to be 
converted, is the catalog specified in the INFILE or INDATASET 
parameter. 

If there are alias entries for OS CVOLs, the master catalog 
always receives alias entries that point to OS CVOLs. 


Order of Catalog Selection for DEFINE 

The order in which catalogs are selected when an entry is 
defined is: 

1. If a catalog is specified in the CATALOG parameter, that 
catalog is selected to contain the entry to be defined. 

2. When a non-VSAM generation data group (GDG) data set is 
defined, the catalog containing the GDG base is selected to 
contain the non-VSAM entry still to be defined. Otherwise, 

3. The first user catalog specified in the current job step 
(STEPCAT) or, if none is specified for the job step, the 
first user catalog in the current job (JQBCAT), is selected 
to contain the entry to be defined. ( ,f Direct Allocation 
Using JOBCAT and STEPCAT DD Statements" on page 11 describes 
how you can specify a user catalog for the current job step 
or current job.) Otherwise, 

4. If no user catalog is specified for the current job step or 
job, and the entry f s name is a qualified name, and the first 
qualifier (that is, the first one to eight characters before 
the period) is the same as: 

• The name of a user catalog, or 

• The alias of a user catalog, 

the catalog so identified is selected to contain the entry 
to be defined. 

5. If no catalog has been identified, either explicitly or 
implicitly, VSAM defines an object in the master catalog. 
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Order of Catalog Search for DELETE 


If this is not a generic delete, the order in which catalogs are 
searched to locate an entry to be deleted is: 

1. If a catalog is specified in the CATALOG parameter, only 
that catalog is searched. If the entry is not found, a "no 
entry found" error is returned to the user. Otherwise, 

2. Any user catalog(s) specified in the current job step Cwith 
a STEPCAT DD statement) is searched. If more than one 
catalog is specified for the job step, the catalogs are 
searched in order of concatenation. If the entry is found, 
no other catalog is searched. 

If a STEPCAT catalog is specified and the entry is not 
found, the JOBCAT catalog is not searched. The catalog 
search continues with step 3 below. 

If no STEPCAT catalog is specified for the job step, and a 
user catalog is specified for the current job (with a JOBCAT 
DD statement), the JOBCAT catalog(s) is searched. If more 
than one catalog is specified for the job, the catalogs are 
searched in order of concatenation. If the entry is found, 
no other catalog is searched. Otherwise, 

3. If the entry is identified with a qualified entryname and 
its first qualifier is the same as: 

• The name of a user catalog, or 

• The alias of a user catalog, or 

• The alias of an OS CVOL, 

the user catalog or OS CVOL so identified is searched. If 
the entry is found, no other catalog is searched. 

Otherwise, 

4. If the entry is not found, the master catalog is searched. 

If the entry is not found in the master catalog, a "no entry 
found" error is returned to the user. 

If this is a generic delete, the order in which catalogs are 
searched to locate all applicable entries to be deleted is: 

1. If a catalog is specified in the CATALOG parameter, only 
that catalog is searched. If an entry that matches the 
supplied qualifiers is not found, a "no entry found" error 
is returned to the user. Otherwise, 

2. Any user catalog(s) specified in the current job step Cwith 
a STEPCAT DD statement) is searched. If more than one 
catalog is specified for the job step, the catalogs are 
searched in order of concatenation. The JOBCAT catalog is 
not searched. The catalog search continues with step 3 
below. 

If no STEPCAT catalog is specified for the job step, and a 
user catalog is specified for the current job (with a JOBCAT 
DD statement), the JOBCAT catalog(s) is searched. If more 
than one catalog is specified for the job, the catalogs are 
searched in order of concatenation. The catalog search 
continues with step 3 below. 

3. If the entry is identified with a qualified entryname and 
its first qualifier is the same as: 

• The name of a user catalog, or 

• The alias of a user catalog, or 

• The alias of an OS CVOL, 
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the user catalog or OS CVOL so identified is searched. The 
catalog search continues with step 4 below. Otherwise, 

4. The master catalog is searched. If an entry has not been 
found in any of the catalogs searched that matches the 
supplied qualifiers, a ,! no entry found” error is returned to 
the user. 

CAUTION: If the generic form of entryname is used to delete 

catalog entries, and the catalog is not specified via the 
CATALOG parameter, entries may be deleted from the master 
catalog if they meet the specified qualification. 


Order of Catalog Search for LISTCAT 

When the ENTRIES parameter is not specified, or when the command 
is not executed through TSO and it is not a generic LISTCAT, the 
order in which catalogs are searched when entries are to be 
listed using the LISTCAT command is: 

1. If a catalog is specified in the CATALOG parameter, only 
that catalog is listed. Otherwise, 

2. The first user catalog specified in the current job step 
(STEPCAT) or, if none is specified, the first user catalog 
specified in the current job (JOBCAT) is listed. Otherwise, 

3. If no user catalog is specified in the current job step or 
job, the master catalog is listed. 

If the command is not a generic LISTCAT and if the ENTRIES or 
LEVEL parameter is specified or when the command is executed 
through TSO, the order in which catalogs are searched when 
entries are to be listed using the LISTCAT command is: 

1. If a catalog is specified in the CATALOG parameter, only 
that catalog is searched. If the entry is not found, a "no 
entry found” error is returned to the user. Otherwise, 

2. Any user catalog(s) specified in the current job step 
(STEPCAT) or, if none is specified for the job step, any 
user catalog(s) specified for the current job (JOBCAT). If 
more than one catalog is specified for the job step or job, 
the job step or job catalogs are searched in order of 
concatenation. If the entry is found, no other catalog is 
searched. Otherwise, 

3. If the entry is not found, and the entry*s name is a 
qualified name, and the first qualifier (that is, the first 
1 to 8 characters before a period) is the same as: 

• The name of a user catalog, or 

• The alias of a user catalog, or 

• The alias of an OS CVOL, 

that user catalog or OS CVOL is searched. If the entry is 
found, no other catalog is searched. Otherwise, 

4. The master catalog is searched. If the entry is not found, 
a "no entry found" error is returned to the user. 
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When the ENTRIES parameter is specified and this is a generic 
LISTCAT, the order in which catalogs are searched when entries 
are to be listed using the LISTCAT command is: 

1. If a catalog is specified in the CATALOG parameter, only 
that catalog is searched. If an entry is not found that 
matches the supplied qualifiers, a "no entry found" error is 
returned to the user. Otherwise, 

2. Any user catalogCs) specified in the current job step 
(STEPCAT) or, if none is specified for the job step, any 
user catalogCs) specified for the current job (JOBCAT). If 
more than one catalog is specified for the job step or job, 
the job step or job catalogs are searched in order of 
concatenation. The catalog search continues with step 3 
below. Otherwise, 

3. If the entry f s name is a qualified name, and the first 
qualifier (that is, the first 1 to 8 characters before a 
period) is the same as: 

• The name of a user catalog, or 

• The alias of a user catalog, or 

• The alias of an OS CVOL, 

that user catalog or OS CVOL is searched. The catalog 
search continues with step 4 below. Otherwise, 

4. The master catalog is searched. If an entry has not been 
found in any of the catalogs search that matched the 
supplied qualifiers, a "no entry found" error is returned to 
the user. 


MASS STORAGE SYSTEM (MSS) 

The IBM 3850 Mass Storage System can be used to store a massive 
amount of data online to the operating system. It is described 
in ln, t c. pd yQ..ti Q a....tp, t he, IBM . 58 .5 0. . SysimJ LM S S l • 

When you have the Mass Storage System, you can define VSAM data 
spaces, user catalogs, and data sets and non-VSAM data sets on 
mass storage volumes. The master catalog cannot be stored on a 
mass storage volume. 

A catalog may have defined in it both objects stored on direct 
access storage volumes and objects stored on mass storage 
volumes. In particular, the data component of a key-sequenced 
cluster may be stored on a mass storage volume and the index 
component on a direct access storage volume, or vice versa. 

Space for an object larger than one cylinder that is stored on a 
mass storage volume should be allocated in cylinders to optimize 
data transfer (staging and destaging) between mass storage and 
direct access storage. 

Data stored in the Mass Storage System is staged from mass 
storage to a direct access storage staging drive when the object 
to which the data belongs is opened or when the data is 
requested. It is destaged from the staging drive to mass 

storage when the object is closed. ( In .tr.. Q i.Q.0 ±Q.... t h & I B M 

I SM. .S ystm JL MSS l tells which direct access storage 

devices can be used for staging.) 

Access method services for the Mass Storage System provides a 
set of commands for the management of mass storage volumes. 

These commands are described in 

fen enpp , JLof or m a ..t.l ftn > 

Access method services for managing catalogs provides parameters 
for options of the Mass Storage System in the DEFINE and ALTER 
commands, which enable you to specify how a VSAM data set that 
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is stored on a mass storage volume is to be staged and destaged 
and how a user catalog that is stored on a mass storage volume 
is to be destaged. These parameters are described in this book. 

The staging attributes, BIND, CYLINDERFAULT, and STAGE, affect 
performance. BIND causes an object to be staged when it is 
opened and to be retained (bound) in direct access storage. 
CYLINDERFAULT causes portions of an object to be staged only as 
needed during processing. STAGE is a compromise: the object is 
staged when it is opened, but not retained in direct access 
storage. When the staging activity of other objects is light, 
STAGE can achieve results similar to BIND: the data might 
remain in direct access storage, available for requests for 
access without staging. When the staging activity of other 
objects is heavy, STAGE can achieve results similar to 
CYLINDERFAULT: the data might not remain in direct access 

storage and might have to be restaged when needed. 

A user catalog that is stored on a mass storage volume is always 
staged and bound when it is opened—that is, it is retained in 
direct access storage until it is closed. Not binding a user 
catalog might degrade performance. 

For recoverable catalogs, a catalog recovery area (CRA) is 
opened when it is first needed, and remains open for as long as 
the user catalog is open. Because of this, the CRA volume must 
remain mounted during that period of time. 

The destaging attributes, DESTAGEWAIT and NODESTAGEWAIT, affect 
data integrity. DESTAGEWAIT causes VSAM to return control to 
the program that closes an object synchronously—only after 
destaging is complete. VSAM can notify the program whether 
destaging was successful. NODESTAGEWAIT causes VSAM to return 
control to the program asynchronously—as soon as the object is 
closed, but before it has been destaged. 

A failure in destaging causes a message to be written to the 
operator. With DESTAGEWAIT, an error code is also returned from 
CLOSE to the processing program. But there are no recovery 
procedures for a program to undertake: One use of DESTAGEWAIT 
is for a processing program to periodically issue a temporary 
CLOSE of a bound object to cause it to be destaged at various 
checkpoints. The processing program can terminate processing if 
a failure occurs in destaging. The last copy destaged would be 
the copy to fall back to, pending correction of the error that 
caused the failure. 

A data component that is defined with the ERASE parameter and 
stored on a mass-storage volume, is overwritten with binary 
zeros on the staging drive after it is destaged. 

Note: On mass storage volumes, a GDG data set may not be 

scratched when it is automatically uncataloged, even if the 
SCRATCH option was specified in the DEFINE. 
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This chapter describes: 

• IF-THEN-ELSE command sequence; which is used to control 
command execution on the basis of condition codes 

• DO-END command sequence; which specifies more than one 
functional access method services command and its parameters 

• NULL command; which specifies that no action is to be taken 

• SET command; which is used to reset condition codes 

• PARM command; which is used to specify diagnostic aids and 
printed output options 

These commands cannot be used when access method services is 

being executed under TSQ. 


CONDITION CODES 


The condition codes that are tested in the IF-THEN-ELSE command 
sequence follow: 

Code Explanation 

0 Indicates that the function was executed as directed and 
expected. Some informational messages might be issued. 

4 Indicates that some problem was met in executing the 

complete function; but it was possible to continue. The 
continuation might not provide the user with exactly what 
is wanted; but no permanent harm will have been done by 
such continuation. A warning message was issued. An 
example of the kind of problem encountered is: The system 
was unable to locate an entry in a LISTCAT command. 

8 Indicates that a requested function was completed; but 
major specifications were unavoidably bypassed. For 
example, an entry to be deleted or altered could not be 
found in the catalog; or a duplicate name was found while 
an entry was being defined and the define action was 
terminated. 

12 Indicates that the requested function could not be 

performed. This condition code is set as a result of a 
logical error. A logical error condition exists when 
inconsistent parameters are specified; when required 
parameters are missing; or when a value specified for key 
length; record size; or buffer space is too small or too 
large. More information on logical errors that occur 
during VSAM record processing is in 
Macro Instruction Reference . 

16 Indicates that a severe error occurred that caused the 
remainder of the command stream to be flushed. This 
condition code might result in the following examples: A 
system output data set cannot be opened Ca SYSPRINT DD 
statement was missing; for example); an unrecoverable error 
occurred in a system data set; or access method services 
encountered improper IF-THEN-ELSE command sequences. 

Condition codes that are tested in the IF-THEN-ELSE command 
sequence or set by the SET command cannot be passed from one job 
step to the next. However; the maximum condition code value 
established by any previous functional command or SET command is 
passed to the operating system when the access method services 
processor returns control to the system. 
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IF-THEN-ELSE COMMAND SEQUENCE 

The IF-THEN-ELSE command sequence is used to control command 
execution. 

The format of the IF-THEN-ELSE command sequence iss 



IF 

{LASTCCIMAXCC} comparand number 


THEN! .comma ndl 


DO 


.command asi 


END] 


[ELSE[ command 1 


DO 


command set 


END]] 


where: 

IF 

specifies that one or more functional commands are to be 
executed based on a test of a condition code. The 
condition code is set by a SET command or is set to reflect 
the completion status of previous functional commands. 

LASTCC 

specifies that the condition code value that resulted from 
the immediately preceding function command is to be 
compared, as indicated by the comparand, to the number 
following the comparand. For the meaning of condition 
codes, see "Condition Codes.” 


MAXCC 

specifies that the maximum condition code value that has 
been established by any previous function command or by a 
SET command is to be compared, as indicated by the 
comparand, to the number following the comparand to 
determine whether the THEN action is to be performed. For 
the meaning of condition codes, see "Condition Codes." 

&flmp.ar:a nrf 

specifies the comparison to be made between the variable 
and the following number. There are six possible 
comparisons: 

Equal, specified as 1=1 or ' EQ 1 Not equal, specified as 
f -=* or 'NE' 

Greater than, specified as f > f or f GT* 

Less than, specified as f < f or f LT f 

Greater than or equal, specified as •>=■ or 'GE 1 

Less than or equal, specified as *<=* or "LE* 

nmS s& L. 

specifies the decimal integer that is to be compared with 
MAXCC or LASTCC. The number can be up to 10 digits long. 
Values greater than 16 are reduced to 16; both LASTCC and 
MAXCC are initialized to zero upon entry to access method 
services. For the meaning of condition codes, see 
"Condition Codes." 

THEN 

specifies that a single command or a group of commands 
(introduced by DO) is to be executed if the comparison was 
true. THEN can be followed by another IF command. 
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ELSE 


specifies that a single command or a group of commands 
(introduced by DO) is to be executed if the previous 
comparison is false. ELSE can be followed by another IF 
command. 

When an IF command appears in a THEN or ELSE clause, it is 
called a nested IF command. The maximum level of nesting 
allowed is 10, starting with the first IF specified. 

Within a nest of IF commands, the innermost ELSE clause is 
associated with the innermost THEN clause, the next innermost 
ELSE clause with the next innermost THEN clause, and so on. (To 
say it another way, each ELSE is matched with the nearest 
preceding unmatched THEN.) Should there be an IF command that 
does not require an ELSE clause, follow the THEN clause with a 
null ELSE clause (ELSE), unless the nesting structure does not 
require one. 


DO-END COMMAND SEQUENCE 

DO 

specifies that the group of commands that follow is to be 
treated as a single unit, that is, to be executed as a 
result of a single IF command. The set of commands is 
terminated by END. A command following a DO must begin on 
a new line. 

END 

specifies the end of a set of commands initiated by the 
nearest unended DO. END must be on a line by itself. 

Note: Continuation characters should not be used in the 

DO-END sequence; they may be taken as a null command or 
cause unpredictable results. 


NULL COMMANDS 


If THEN or ELSE is not followed by a continuation character or 
by a command in the same record, the THEN or ELSE results in no 
action. 

The null command supports an ELSE command that balances an 
IF-THEN-ELSE command sequence, and allows null THEN commands. 

The null command is, in essence, a THEN or ELSE command that is 
not followed by a command continuation character. 

If you want to indicate a null ELSE command, specify: 

ELSE 

If you want to indicate a null THEN command, specify: 

IF ... THEN 
ELSE ... 

The null command is used to indicate that no action is to be 
taken if the IF clause is satisfied (a null THEN command), or if 
the IF clause is not satisfied (a null ELSE command). 


SET COMMAND 


The SET command is used to change or reset a previously defined 
condition code. (For the meaning of condition codes, see 
"Condition Codes.") It is possible to terminate all processing 
merely by setting MAXCC or LASTCC to 16. 
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The format of the SET command is: 


SET 


£ MAXCCILASTCC}= number 




where: 

SET 

specifies that a condition code value is to be set. A SET 
command that follows a THEN or ELSE that is not executed 
does not cause the value of LASTCC or MAXCC to be altered. 


MAXCC 

specifies that the value to be reset is the maximum 
condition code set by a previous functional command. 

Setting MAXCC does not affect the value of LASTCC. 

LASTCC 

specifies that the value to be reset is the condition code 
set by the immediately preceding functional command. 

numhfic 

specifies the value to be assigned to MAXCC or LASTCC. The 
maximum value that can be assigned is 16; a greater value 
will be reduced to 16. If the value assigned to LASTCC is 
greater than the value of MAXCC, MAXCC is set equal to the 
higher value. 


PARM COMMAND 


The PARM command specifies processing options to be used during 
execution. These options remain in effect until changed by 
another PARM command. You can also specify these options in the 
PARM field of an EXEC statement (in the JCL). 

The format of the PARM command is: 


PARM 

[TESTt 


{[TRACE3 


[AREAS(areaid[ areaid...3)3 


EFULLC CdmaeidE aamiilE £&yn±23 3) 


[ [dump-id... 3... 3 3 3 1 


OFFJ3 3 


EGRAPHICS(CHAIN(£haiQ3|TABLECmnamfi3 33 


[margins(X afimanaaji risb.t morale 3 3 


where: 

TEST( 

£1TRACE] 

E AREAS (areaid E >1)] 

EFULLC [.dumpjLdC £L <m n±±l saml 211) 

E( dumpid *..)...])]I 
OFF}) 

specifies the diagnostic aids to be used. After the TEST 
option has been established, it remains in effect until it 
is reset by another PARM command. The TRACE, AREAS, and 
FULL parameters may be used concurrently. 

TRACE 

specifies that trace tables are to be listed whenever 
the built-in dump points of the processor are 
encountered. 

areas (gx.ejt.j d E ar m id« »>I) 

identifies modules that are to have selected variables • 
dumped at their dump points. Each item in the areaid \ , 

is a 2-character area identifier defined within the 
implementation. For more information, see Access 
H e. th .Q d.S .. Q ryi< p .^js, L .qLSL lg .. 
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FULL( CdmaaLdt CQ Mnl ll cmm&Zl 1) t Cdymaid* 

specifies that a region dump, as well as the trace 
tables and selected variables, is to be provided at 
the specified points, dumpid specifies the 
4-character identifier of the dump point. For more 
information, see A c c e ss . . Me lLod* 


is a decimal integer that specifies the number of 
times the program is to go through the dump point 
before beginning the dump listing. (Default is 
1 .) 


£g ju nt2 

is a decimal integer that specifies the number of 
times through the dump point that dumps are to be 
listed. (Default is 1.) 

If the FULL keyword is used, an AMSDUMP DD statement 
must be provided. For example: 

//AMSDUMP DD SYS0UT=A 


OFF 

specifies that testing is to stop. 

GRAPHICS (CHAIN (shaijQ) I TABLE ) ) 

specifies the print chain graphic character set or a 
special graphics table to be used in producing the output. 

CHAIN(AN|HN|IQN|RN|SN|TN) 

specifies the graphic character set of the print 
chains you want to use. PN is used by the processor 
unless explicitly directed to use another set of 
graphics. 

TABLE(moamfi) 

specifies the name of a usei—supplied table. This 
256-byte table defines the graphics for each of the 
256 possible bit patterns. Any character to be 
printed is translated to the bit pattern found in such 
a table at the position corresponding to its numeric 
value (0 through 255). If the print chain does not 
have a graphic for a byte f s bit pattern, the table 
should specify a period as the output graphic. The 
table must be stored as a module accessible through 
the LOAD macro (VS). 

MARGI NS (±£f ±m n m n r i ght ma x gin) 

specifies that the margins of input records on which 
command statements are written are to be changed. The 
normal left and right margins are 2 and 72, respectively. 

If MARGINS is coded, all subsequent input records are 
scanned in accordance with the new margins. This feature 
may be used in conjunction with the comment feature: 
Respecification of margins could be used to cause the /X 
and */ characters to be omitted from the scan and thus 
cause comments to be treated as commands. 

■lAf.t mar gin 

specifies the location of the left margin. 


specifies the location of the right margin. The right 
margin value must be greater than the left margin 
value. 


Chapter 3. Controlling Command Execution 25 



COMMON CONTINUATION ERRORS IN CODING CONTROL COMMANDS 


The continuation rules must be used cautiously when modal 
commands appear in the input stream. (See f, How to Continue \ 

Commands and Parameters” on page 7.) The following examples 
show common continuation errors: 

• IF LASTCC * 0 - 
THEN 

LISTCAT 

A continuation mark (hyphen) is missing after the THEN 
keyword. A null command is assumed after the THEN keyword* 
and the LISTCAT command is unconditionally executed. 

• IF LASTCC = 0 - 
THEN - 

REPRO ... 

/^ALTERNATE PATH*/ 

ELSE - 
PRINT ... 

Because no continuation mark (hyphen) follows the comment* a 
null command is assumed. The ELSE keyword will not match up 
with the THEN keyword. Note the correct use of the 
continuation marks on the other records. 

• IF LASTCC = 0 - 
THEN - 

REPRO ... 

ELSE ~ 

PRINT ... 

Because a blank line with no continuation mark (hyphen) 
follows the ELSE keyword* the ELSE becomes null and the 
PRINT command is unconditionally executed. 

• PARM TEST ( - /^COMMENT*/ 

TRACE) 

Because characters other than blanks appear between the 
continuation mark (hyphen) and the end of the record* the 
PARM command will not be continued onto the second record. 

• PARM TEST ( TRA+ 

/XFIELD CONTINUATION*/ 

CE) 

Because no continuation was indicated* the end of the PARM 
command is found after the second record. The command is 
rejected. 


/T - 
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CONTROL COMMAND EXECUTION EXAMPLES 


The examples that follow show the use of the IF-THEN-ELSE 
command sequence/ the SET command, and the PARM command. 


Control Command Execution with Nested IF Commands: Example 1 

In this example, nested IF commands are used to determine 
whether a REPRO, DELETE, or PRINT command is to be executed. 

IF LASTCC > 4 - 

THEN IF MAXCC < 12 - 

THEN REPRO... 

ELSE DELETE... 

ELSE IF LASTCC = 4 - 

THEN 

ELSE PRINT... 

This example specifies that, if the value of LASTCC is greater 
than 4, the value of MAXCC is to be tested. If the value of 
MAXCC is less than 12, the REPRO command is executed; if the 
value of MAXCC is 12 or greater, the DELETE command is executed 
instead. Again, if the value of LASTCC is 4 or less, LASTCC is 
tested for being exactly 4s No action is to be taken in this 
case. If, however, LASTCC is less than 4, the PRINT command is 
to be executed. 


Control Command Execution with Nested IF Commands: Example 2 

In this example, nested IF commands are used to determine 
whether a REPRO or PRINT command is to be executed. 

IF LASTCC > 4 - 

THEN IF MAXCC <12 - 

THEN REPRO ... 

ELSE 

ELSE IF LASTCC = 4 - 

THEN PRINT ... 

Should the first IF command determine that LASTCC is greater 
than 4, and the second IF command determine that MAXCC is 12 or 
greater, no functional commands will be executed. The null ELSE 
command is employed here to specify that the next ELSE is to 
correspond to the first THEN. 


Control Command Execution Using MAXCC Parameter: Example 3 

In this example, if the maximum condition code is 0, an entry 
from a catalog is listed and a data set is printed. 

IF MAXCC=0 THEN DO 

LISTCAT CATALOG (AMASTCAT/MST27) ENT (MN01.0005) 

PRINT INFILE (AJK006) 

END 

ELSE ... 
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Control Command Execution Using LASTCC Parameter: Example 4 


If you want to list a catalog and print a data set if the last 
condition code is 0, but want to list its catalog entry before 
and after a VERIFY command if the last condition code is greater 
than 0, specify! 

IF LASTCC = 0 THEN DO 
LISTCAT 

PRINT INFILE CAJK006) 

END 

ELSE DO 

LISTCAT ENTRY CAJK006) ALL 
VERIFY FILE (AJKJCL6) 

LISTCAT ENTRY (AJK006) ALL 
END 


Control Command Execution with LASTCC Value Established: Example 5 

If you want to set the last condition code established to 12, 
specify: 

SET LASTCC=12 


Control Command Execution Replacing NAXCC Value: Example 6 

If you want to replace the highest condition code established in 
processing so far with 8, specify: 

SET MAXCC=8 
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C HA P T E R < tt , J U N CX I QN A L ^ C QMI1AM B ^£.Q.R M AI 


This chapter contains the access method services functional 
commands for VSAM catalogs, OS CVOLs, and for VSAM and non-VSAM 
data sets. The commands are arranged alphabetically, with a 
summary of the required and optional parameters following each 
command section. The required parameters are arranged in 
alphabetic order, with a discussion of the parameter and an 
abbreviation following. The optional parameters are in the same 
format and follow the required parameters. 

Examples of how each command is used are provided at the end of 
each command. 

For an explanation of the symbols used in the command formats, 
see "Notational Conventions" on page vi. See "How to Code 
Subparameters" on page 5 for coding conventions that apply to 
the subparameters used in access method services commands. 


FUNCTIONAL COMMAND FORMAT SUMMARY 

This section provides reference information about the following 
functional commands. 

• ALTER, which is used to alter attributes of data sets and 
catalogs that have already been defined. 

• BLDINDEX, which builds alternate indexes for existing data 
sets. 

• CHKLIST, which lists tape data sets opened during a 
checkpoint. 

• CNVTCAT, which converts OS CVOL entries into VSAM catalog 
entries. 

• DEFINE, which defines the following objects: 

— DEFINE ALIAS, which defines an alternate name for a 
non-VSAM data set or a user catalog. 

DEFINE ALTERNATEINDEX, which defines an alternate index. 

— DEFINE CLUSTER, which defines a cluster for a 

key-sequenced, entry-sequenced, or relative record data 
set. 

DEFINE GENERATIONDATAGROUP, which creates a catalog 
entry for a generation data group. 

— DEFINE NONVSAM, which defines a catalog entry for a 
non-VSAM data set. 

— DEFINE PAGESPACE, which defines an entry for a page 
space data set. 

— DEFINE PATH, which defines a path directly over a base 
cluster or over an alternate index and its related base 
cluster. 

- DEFINE SPACE, which defines a VSAM data space. 

DEFINE USERCATALOGlMASTERCATALOG, which defines a user 
catalog. 
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• DELETE, which deletes catalogs, VSAM data sets, and non-VSAM 
data sets. 

• EXAMINE, which is used to analyze and report on the 
structural consistency of the index component and/or data 
component of a key-sequenced data set cluster. 

• EXPORT, which disconnects user catalogs and exports VSAM 
data sets. 

• EXPORTRA, which recovers VSAM and non-VSAM catalog entries 
from catalog recovery areas, and recovers data for VSAM 
objects (clusters and alternate indexes) by means of catalog 
recovery areas. 

• IMPORT, which connects user catalogs and imports VSAM data 
sets. 

• IMPORTRA, which reconstructs multiple VSAM data sets from a 
data set created by the EXPORTRA command. 

• LISTCAT, which lists catalog entries. 

• LISTCRA, which lists or compares the contents of a given 
catalog recovery area. 

• PRINT, which is used to print VSAM data sets, non-VSAM data 
sets, and catalogs. 

• REPRO, which is used to copy VSAM and non-VSAM data sets, to 
copy catalogs, and to unload and reload VSAM catalogs. 

• RESETCAT, which compares catalog entries with catalog 
recovery area (CRA) entries in order to regain access to 
catalog data. 

• VERIFY, which causes a catalog to correctly reflect the end 
of a data set after an error occurred while closing a VSAM 
data set. The error may have caused the catalog to be 
incorrect. 
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ALTER 


ALTER 

The ALTER command modifies the attributes of previously defined 
catalog entries. The format of this command isi 


ALTER 


[ADDVOLUMESt volser ! volser ...])! 
[ATTEMPTS! number )3 

[AUTHORIZATION( entrvpoint ! string !)I 
[BUFFERSPACEf size )] 

ICODEC code )] 

[CONTROLPWC password ) 1 
[DESTAGEWAIT|NODESTAGEWAIT! 

[EMPTY|N0EMPTY1 
[ERASE|NOERASE3 
[EXCEPTiONEXiT[ S n t r ypgi n.tn 
[FlLECddnameJ 1 

[FREESPACEC CX-perce n t 1 CA-percentD )] 

(INHIBIT|UNINHIBIT1 
t KEYS (length p ffe etn 
[MASTERPWIp ass M c r d l! 

[NEWNAMEt newname )) 

[NULLIFYt 

[AUTHORIZATION(MODULE|STRING)I 
[CODE] 

[CONTROLPW] 

[EXCEPTIONEXIT] 

[MASTERPW3 

[OWNER! 

[READPW1 

[RETENTION] 

EUPDATEPW])] 

[ OWNER C ow n er-id) 1 
[ READPW( password )] 

[RECORDSIZEtay.er.a ge maximum )! 
[REMOVEVOLUMESt volser [ volser ...3 )! 

[SCRATCH|NOSCRATCH 3 

[ shareoptions (cr_ Qs .sr.egj, on [ crogs s yste m])! 
[STAGE|BIND|CYLINDERFAULT3 
[TQt date )I FORt days )] 

[UNIQUEKEY|NONUNIQUEKEY] 

[UPDATE|NOUPDATE] 

[UPDATEPWt password )] 

[UPGRADE|NOUPGRADE3 
[WRITECHECKIN0WRITECHECK3 


[ catalog t catn em e [ /p gg s wc cd1 ) 3 


Entry Types That Can Be Altered 

An "X" in Figure 2 on page 32 indicates you can alter the value 
or attribute for the type of catalog entry specified. KEYS and 
RECORDSIZE, when specified for a cluster or alternate index, 
apply to its data component entry only, and not to the cluster 
or alternate index entry. Some attributes can be specified only 
for the cluster’s or alternate index's data or index component 
entry—you must identify the component with its entryname. You 
can use the LISTCAT command to determine the names generated for 
the object's components. 

When you identify a group of entries with a generic name, 
entries whose entrynames match the supplied qualifiers are 
altered if they contain the type of information specified with 
the ALTER command's other parameters. 

You cannot alter the following types of entries! alias entries* 
a catalog's data or index component entries, or a master 
catalog's self-describing entries. 
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ALTER 


Type of Catalog Entry 


Attributes that 
can be altered 


ADDVOLUME 


ATTEMPTS 


AUTHORIZATION 


BIND 


BUFFERSPACE 


CODE 


CONTROLPW 


CYLINDERFAULT 


DESTAGEWAIT 


EMPTY 


ERASE 


EXCEPTION EX IT 



FOR 




FREESPACE 

INHIBIT 

KEYS 

MASTERPW 

NEWNAME 

NODESTAGE WAIT 

NOEMPTY 

NOERASE 

NOUNIQUEKEY 

NOSCRATCH 

NOUPDATE 

NOUPGRADE 

NOWRITECHECK 






Figure 2 (Part 1 of 2). ALTER Parameters and the Entry Types to Which Each Applies 
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ALTER 


Attributes that 
can ba altered 



NULLIFY 

D 

D 

D 

a 

a 

a 

a 

a 

B 

D 

D 

AUTHORIZATION 

D 

D 

D 

a 

D 

a 

D 

a 

B 



CODE 

D 

D 

1 

a 

a 

a 

a 

n 

B 



CONTROLPW 

D 

D 

D 

D 

a 

a 

a 

D 

B 



EXCEPTION EX IT 


D 

D 


B 

a 






MASTERPW 

D 

D 

D 

a 

D 

D 

a 

a 

B 



OWNER 

D 

D 

n 


a 

a 

a 

B 

B 

B 

B 

READPW 

D 

D 

b 

b 

D 

D 

D 

a 

B 


IJ 

RETENTION 

X 



a 



D 

B 

B 

B 

O 

UPDATEPW 

D 

D 

D 

a 

D 

D 

a 

B 

B 


ZJ 

OWNER 
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D 

D 

a 

a 

D 

a 

B 

B 

B 

D 

READPW 

D 

D 

D 

a 

D 

D 

D 

B 

B 



RECORDSIZE 

D 

D 


D 

X 







REMOVEVOLUMES 


X 

X 


X 

X 






SCRATCH 











X 

SHAREOPTIONS 


X 

X 


X 

X 






STAGE 


X 

X 


X 

X 






TO 

X 



X 



X 

X 

X 

X 

X 

UNINHIBIT 


X 

X 


X 

X 






UNIQUEKEY 


X 










UPDATE 








X 




UPDATEPW 

X 

X 

X 

X 

X 

X 

X 

X 

X 



UPGRADE 

X 











WRITECHECK 


X 

X 


X 

X 








Figure 2 (Part 2 of 2) . ALTER Parameters and the Entry Types to Which Each Applies 
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ALTER 

ALTER PARAMETERS 


Required Parameters 

fiCLfcr yna m e C /easaw R r .d 3 

names the entry to be altered and supplies a password. 

When attributes of a catalog are to be altered^ entryname 
must specify the catalog name. 

For a description of how to specify a generic name in order 
to alter multiple entries with one ALTER command/ see 
CadbalfliSLjLdmi. a i. st ca Ai aaJa yidg . See this guide also for a 
description of how to alter data or index entrynames or 
cluster entry subparameters. 

If you are renaming a member of a non-VSAM partitioned data 
set/ the entryname must be specified in the format: 
pdsname(membername). 

specifies the password of the entry or catalog to be 
altered. 

If you are altering a password-protected entry in a 
password-protected catalog/ you must specify a 
password. The password can be specified with the 
entryname or in the CATALOG parameter. 

• Use the master password for the entry or for the 
catalog that contains the entry for an alternate 
index/ cluster/ page space/ path/ user catalog, 
data, or index. RACF: The alter RACF authority 
for an entry or for the catalog is required. 

• If a data or index component entry is to be 
altered, use the master password of the cluster 
component or catalog. RACF: The alter RACF 
authority for a cluster component or a catalog is 
required. 

• Use the update- or higher-level password of the 
catalog that contains the entry for non-VSAM and 
generation data group (GDG). RACF: The update or 
higher RACF authority to the catalog is required. 


Optional Parameters 


ADDVQLUMESC volser C volser 3) 

specifies volumes to be added to the list of candidate 
volumes. When you specify ADDVOLUMES, the FILE parameter 
must also be specified to identify the volumes being added. 
The volumes to be added as candidate volumes must already 
be owned by the catalog that contains the entry being 
altered. (Space must have been defined on a volume to be 
added or the volume must have been identified as a 
candidate volume.) 

Abbreviation: AVOL 

ATTEMPTS (moak&c) 

specifies the maximum number of times the operator can try 
to enter a correct password in response to a prompting 
message. 

This parameter only has effect when the entry*s master 
password is not null. A prompting message is issued only 
if the user has not already supplied the appropriate 
password. 
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ALTER 


nmh&s: 

is an integer from 0 to 7 and can be expressed in 
decimal (n), hexadecimal (X^ 1 ), or binary (B'n 1 ) 
form. 

Nhen ATTEMPTS(O) is coded, the operator is not 
prompted and is not allowed to enter a password from 
the console. 

Note to TSO users: At a TSO terminal, the logon 
password is checked first, before the user is prompted 
to supply a password. Checking the logon password 
counts as one attempt to obtain a password. If 
ATTEMPTS is not specified, the user has one attempt to 
supply the password, because the default is 2. 

Abbreviation: ATT 

AUTHORIZATION(jgntnygLfiiiiiC sicingl) 

specifies that a usei—security-verification routine (USVR) 
is available for additional security verification. 

sn tr yp p i nt 

specifies the name of the USVR. 

stci-pg 

specifies information to be passed on to the USVR when 
it receives control to verify authorization. 

Abbreviation: AUTH 

BUFFERSPACE( size ) 

specifies the minimum space to be provided for buffers. 

It is recommended that the amount specified be not less 
than the amount specified in the original definition. If 
the amount is less, VSAM attempts to get enough space to 
contain two data component control intervals and, if the 
data is key-sequenced, one index component control 
interval. BUFFERSPACE can be specified only for a catalog, 
or the data component of a cluster or alternate index. 

specifies the amount of space to be provided for 
buffers. If you are altering the bufferspace for a 
VSAM catalog on a 3380, the decimal values you can 
specify are 4096, 6144, 8192, 10240, 12288, and 14336. 
If you are altering the bufferspace for a VSAM catalog 
not residing on a 3380, the decimal values you can 
specify are limited to 3072, 4608, 6144, 7680, 9216, 
and 10752. 

size can be expressed in decimal (n), hexadecimal 
(X'n 1 ), or binary (B f n f ) form, but must not exceed 
16776704. If the size specified is less than the 
amount VSAM requires, VSAM gets the amount it requires 
when the data set is opened. 

Abbreviations: BUFSP or BUFSPC 

CATALOG (c a l na m .e c Zp.a s s.wgrd 3) 

specifies the catalog containing the entry to be altered. 
See "Order of Catalog Search for ALTER" on page 15 for 
information about the order in which catalogs are searched. 


specifies the name of the catalog that contains the 
entry. 

Ea.ssHP.r d 

specifies the master password of the catalog that 
contains the entry to be altered. If the entry to be 
altered is password-protected and the catalog is also 
password-protected, a password must be entered, either 
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ALTER 


through this parameter or through the entryname 
parameter. RACFs The alter RACF authority to the 
catalog is required. 


Abbreviation: CAT 
CODE( code ) 

specifies a code name for the entry being altered. If an 
attempt is made to access a password protected entry 
without a password, the code name is used in a prompting 
message. The code enables the operator or TSO terminal 
user to be prompted for the password without disclosing the 
name of the entry. 

If CODE is not specified and an attempt is made to access a 
cluster or component that is password protected without 
supplying a password, the operator or TSO terminal user is 
prompted with the name of the entry. 

CONTROLPWCjB^sSHQTd) 

specifies a control password for the entry being altered. 
Abbreviation: CTLPW 
DESTAGEWAITI MODESTAGEWAIT 

specifies whether a data or index component that is stored 
on a mass storage volume is to be destaged synchronously or 
asynchronously, with respect to the program that closes it. 

These parameters can be specified only for the data or 
index component of a cluster, alternate index, or 
integrated catalog facility catalog. 

DESTAGEWAIT 

indicates that destaging is to be completed before 
control is returned from VSAM to the program that 
issues the CLOSE macro. VSAM can thus notify the 
program whether destaging was successful. 

Abbreviation: DSTGW 

NODESTAGEWAIT 

indicates that notification of unsuccessful destaging 
is to be made only by a message to the operator. 

Abbreviation: NDSTGW 

EMPTYINOEMPTY 

specifies what is to happen when the maximum number of 
generation data sets has been cataloged. 

EMPTY 

specifies that, when the maximum number of generation 
data sets is exceeded, all the generation data sets 
will be uncataloged. 

Abbreviation: EMP 

NOEMPTY 

specifies that when the maximum number of generation 
data sets is exceeded, only the oldest generation data 
set will be uncataloged. 

Abbreviation: N EMP 


/ 4r~ v \ 

vy 
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ERASE I NOERASE 

specifies whether the data component is to be erased when 
its entry in the catalog is deleted. 

ERASE 

specifies the component is to be overwritten with 
binary zeros when its catalog entry is deleted. 

Abbreviation: ERAS 

NOERASE 

specifies the component is not to be overwritten with 
binary zeros when its catalog entry is deleted. 

Abbreviation: NERAS 

EXCEPTIONEXIT iQD±£yE^±^ 

specifies the name of the usei—written routine that 
receives control when an exception (usually an I/O error) 
occurs while the entry’s object is being processed. 

An exception is any condition that causes a SYNAD exit to 
be taken. The object’s exception exit routine is processed 
first, then the user’s SYNAD-exit routine receives control. 

Note: You may not specify this parameter to add an 

exception-exit routine to a VSAM cluster that is cataloged 
in a VSAM catalog created in an 0S/VS2 Release 2 (or lower 
release level) system. 

Abbreviation: EEXT 

FlLE( dd n ame ) 

specifies one of the following: 

• The name of a DD statement that identifies the volume 
whose catalog recovery area contains a copy of the 
catalog entry. For a description of catalog recovery 
area contents for each volume, see Catalog 

A dm i nis- t ra tim j Syjjte . 

• The name of a DD statement that identifies the volume 
of an entry which will be renamed. The entry must be a 
non-VSAM data set or the data or index component of a 
unique cluster, alternate index, or page space. 

• The name of a DD statement that identifies a 
partitioned data set when a member is to be renamed. 

If multiple volumes of different device types are to be 
identified via FILE, you must use concatenated DD 
statements. If you specify ADDVOLUMES or REMOVEVOLUMES, 
the volume(s) being added or removed must be identified. 

If you specify NEWNAME for a non-VSAM data set or the data 
or index component of a unique cluster, alternate index, or 
page space that does not reside on the same volume as the 
catalog recovery area entry, that volume(s) must be 
identified. 

If FILE is not specified, an attempt is made to dynamically 
allocate the catalog recovery area volume(s) or the 
object’s volume. Therefore, the volume must be mounted as 
permanently resident or reserved. 

FREESPACE( QI zEfeC S E QAzJ^jrcen±l ) 

specifies the amount of space (percentage of space) that is 
to be left free after any allocation and after any split of 
control intervals (Cl-percent) and control areas 
(CA-percent). 

The amounts, as percentages, must be equal to or less than 
100. They may be expressed in decimal (n), hexadecimal 
(X’n’), or binary (B’n’) form. If you specify 100% of free 
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spacer one record is placed in each control interval and 
one control interval is placed in each control area. 

This parameter may be specified to alter the data component 
of a cluster or alternate index. 


If the free space is altered after the data set has been 
loaded/ and sequential insert strategy processing is being 
used/ this allocation of free space may not be honored. 

Ahbreviation: FS PC 


INHIBIT|UNINHIBIT 

specifies whether the entry being altered can be accessed 
for any operation or only for read operations. 


INHIBIT 

specifies that the entry being altered is to be 
read-only. 

Abbreviation: INH 


UNINHIBIT 

specifies that the read-only restriction set by a 
previous ALTER or EXPORT command is to be removed. 

Abbreviation: UNINH 

KEYS(Length offset ) 

specifies the length and offset of the object's key. If 
the entry being altered defines an alternate index/ offset 
applies to the alternate key in the data records in the 
base cluster. 


Restrictions: Keys can be specified only if all the 

following are true: 

• The object whose entry is being altered is an alternate 
index/ a path/ a key-sequenced cluster/ or a data 
component of a key-sequenced cluster or alternate 
index. 

• The object whose entry is being altered contains no 
data records. 

• The values for KEYS in the object's catalog entry are 
default values. For default values/ see the DEFINE 
command that defines the object. 

Note: If the values for KEYS in the object's catalog 

entry are not default values/ and ALTER KEYS specifies 
the same nondefault values/ processing continues for 
any other parameters specified on the command/ and no 
error message is issued. 

• The new values for KEYS do not conflict with the 
control interval size specified when the object was 
defined. 

• The key fits within the record whose length is 
specified by the RECORDSIZE parameter. 

• The key fits in the first record segment of a spanned 
record. 


length gJEfsej 

specifies the length of the key (between 1 and 255)/ 
in bytes/ and its displacement from the beginning of 
the data record, in bytes. You can express length and 
offset in decimal (n), hexadecimal CX'n'), or binary 
CB'n') form. 


dC 

V 


4 ' 

\ 
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MASTERPWE password ) 

specifies a master password for the entry being altered. 

For more details about the object's master password/ see 
the DEFINE command that defines the object. 

• If MASTERPW is not specified/ the highest level 
password specified becomes the password for all higher 
levels. 

• The AUTHORIZATION/ CODE/ and ATTEMPTS parameters have 
no effect unless the entry has a master password 
associated with it. 

• With the master password/ all operations are allowed. 

Note: The master password must exist to alter lowei—level 

passwords. It must be the last level of authority to be 
altered when nullifying all levels of authority. 

Abbreviation: MRPW 

NEWNAME(nskamme) 

specifies that the entry to be altered is to be given a new 
name. 

To give the altered entry a new name: 

• Unless the object being renamed is a path/ the object's 
volume must be mounted because the volume f s VTOC is 
modified. 

You can use the FILE parameter to supply a JCL DD 
statement to cause the object's volumeCs) to be 
allocated. If you do not supply a DD statement/ an 
attempt is made to dynamically allocate the object's 
volumeCs). The volumeCs) must be mounted as either 
permanently resident or reserved. 

• If you specify generic names/ you must specify both the 
entryname and the newname as generic names. For 
information on specifying generic names/ see Catalog 
A. d m in i s .t ra .t.i.Q.n,, QMi da . 

• If you are renaming a member of a non-VSAM partitioned 
data set/ the newname must be specified in the format: 
pdsnameCmembername). 

• If you are renaming a VSAM data set that is RACF 
protected/ the existing RACF data set profile will be 
renamed. 

• If a data set profile exists for the new data set name 
prior to the ALTER command/ the command is terminated 
and the data set name and/or protection attributes 
remain unchanged. 

If the old profile cannot be found or cannot be altered 
to the new name, the NEWNAME action will not be 
completed in the catalog/ and an error message will 
indicate why the action was not completed. 

If the rename fails/ it is possible that the object 
exists with both the original and the new name. 

Abbreviation: NEWNM 

NULLIFY(£AUTHORIZATION(MODULE 1STRING)1 
[CODE]EC0NTR0LPW3 EEXCEPTIQNEXIT] 

EMASTERPW][OWNER]EREADPW] 

[RETENTION]EUPDATEPW3) 

specifies that the protection attributes identified by 
subparameters of NULLIFY are to be nullified. Attributes 
are nullified before any respecification of attributes is 
performed. 
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If all levels of passwords are nullified and none are 
respecified, CODE, AUTHORIZATION, and ATTEMPTS have no 
effect. 

Abbreviation: NUL L 

AUTHORIZATION(MODULE|STRING) 

specifies that either the use*—authorization routine 
or the usei—authorization record is to be nullified. 

Abbreviation: AUTH 

MODULE 

specifies that the module name is to be removed 
from the catalog record, but the module itself is 
not to be deleted. Both the usei—authorization 
routine and the usei—authorization record 
(character string) are nullified. 

Abbreviation: MDLE 

STRING 

specifies that the authorization record is to be 
nullified, but the corresponding module is not 
nullified. 

Abbreviation: STRG 


CODE 

specifies that the code name used for prompting is to 
be nullified. 

CONTROLPW 

specifies that the control password is to be 
nullified. 

Abbreviation: CT L PW 
EXCEPTIONEXXT 

specifies that the entry f s exception exit is to be 
nullified. The module name is removed from the 
catalog record, but the exception-exit routine itself 
is not deleted. 

Abbreviation: EEXT 

MASTERPW 

specifies that the master password is to be nullified. 
If a new master password is not specified and if other 
passwords exist, the highest level password that 
exists automatically becomes the password for all 
higher levels, including the master password. 

Abbreviation: MRPW 


OWNER 

specifies that the owner identification is to be 
nullified. 


READPW 

specifies that the read password is to be nullified. 
Abbreviation: RDPW 


RETENTION 

specifies that the retention period which was 
specified in a TO or FOR parameter is to be nullified. 


Abbreviation: RETN 


UPDATEPW 

specifies that the update password is to be nullified. 
Abbreviation: UPDPW 


40 MVS/XA VSAM Catalog: Access Method Services Reference 




ALTER 


OWNER Cp w n e r i d 3 

specifies the owner identification of the entry being 
altered. 

READPW C password 3 

specifies a read password for the entry being altered. 
Abbreviation: RDPW 

RECORDS IZECsyerajgg maxl m ym 3 

specifies new average and maximum lengths for data records 
that will be contained in the object whose entry is being 
altered. 

If the object whose entry is being altered is a path 
pointing to the alternate index, the alternate index is 
altered; if it is a path pointing directly to the base 
cluster, the base cluster is altered. 

If the object whose entry is being altered is an alternate 
index, the length of the alternate key must be within the 
limit specified by maximum. 

Restrictions: RECORDSIZE can be specified only if all of 

the following are true: 

• The object whose entry is being altered is an alternate 
index, a cluster, a path, or a data component. 

• The object whose entry is being altered contains no 
data records. 

• The value for maximum RECORDSIZE in the object f s 
catalog entry is the default value. For default 
values, see the DEFINE command that defines the object. 

Note: If the value for RECORDSIZE in the objects 

catalog entry is not the default value, and ALTER 
RECORDSIZE specifies the same nondefault value, 
processing continues for any other parameters specified 
on the command, and no error message is issued. 

• For an alternate index, if NONUNIQUEKEY is specified, 
the record length to be specified accounts for the 
increased record size resulting from the multiple 
prime-key pointers in the alternate index data record. 

• The maximum record length to be specified is at least 
seven bytes less than control interval size, unless the 
record is a spanned record. 

• The record length to be specified is large enough to 
contain all prime and alternate keys previously 
defined. 

Abbreviation: RECSZ 

REHOVEVOLUMESCyjiI^nC SflJbBficl 3 
has two uses: 

1. REMOVEVOLUMES specifies volumeCs) to be removed from 
the list of candidate volumes associated with the entry 
being altered. If you are also adding volumes, the 
volumes to be removed are removed after the new volumes 
are added to the candidate list. The name of the data 
or index component must be specified in the entryname 
parameter. 

Note: If a volume to be removed contains data that 

belongs to the entry being altered, the volume is not 
removed. 

2. REMOVEVOLUMES specifies volumeCs) from which all VSAM 
data spaces are to be removed and VSAM ownership is to 
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be taken away—without access to the user catalog that 
owns the volume(s). For this use of REMOVEVOLUMES, the 
name of the master catalog and its master password (if 
any) must be specified in the entryname parameter, and 
the FILE parameter is required. (You can have only one 
DD statement with this use of ALTER REMOVEVQLUMES—only 
volumes of the same device type can be processed.) 

For information and cautions about this use of ALTER 
REMOVEVOLUMES, see the sections "VSAM Volume Cleanup" and 
"VSAM Volume Recovery Function" in the Catalog 
Adminls t.ra,d£. * 

Abbreviation: RVOL 

SCRATCH|NOSCRATCH 

specifies whether generation data sets, when they are 
uncataloged, are to be removed from the VTOC of the volume 
on which they reside. 

SCRATCH 

indicates that the data set f s format-1 DSCB is to be 
removed (scratched) from the VTOC so that the data set 
can no longer be accessed. 

Abbreviation: SCR 

NOSCRATCH 

indicates that the data set's format-1 DSCB is not to 
be removed from the VTOC. 

Abbreviation: NSCR 

SHAREOPTIONS(c C£osssxs±£m ]) 

specifies how a data or index component of a cluster or 
alternate index can be shared among users. (For a full 
description of data set sharing, see VSAM Administration 
.Qm.de. ) 

specifies the amount of sharing allowed among regions 
within the same system or within multiple systems 
using global resource serialization (GRS). 

Independent job steps in an operating system or 
multiple systems using GRS can access a VSAM data set 
concurrently. 

To share a data set, each user must specify DISP^SHR 
in the data set's DD statement. The values that can 
be specified are: 

1 

specifies that the data set can be shared by any 
number of users for read processing, or the data 
set can be accessed by only one user for read and 
write processing. With this option, VSAM ensures 
complete data integrity for the data set. 

2 

specifies that the data set can be accessed by 
any number of users for read processing and it 
can also be accessed by one user for write 
processing. With this option, VSAM ensures write 
integrity by obtaining exclusive control for a 
control interval when it is to be updated. 

If a user requires read integrity, it is that 
user's responsibility to use the ENQ and DEQ 
macros appropriately to provide read integrity 
for the data obtained by the program. (For 
information on using ENQ and DEQ, see System 

* ) 
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3 

specifies that the data set can be fully shared 
by any number of users. With this option, each 
user is responsible for maintaining both read and 
write integrity for the data the program 
accesses. 

User programs that ignore the write integrity 
guidelines can cause VSAM program checks, lost or 
inaccessible records, uncorrectable data set 
failures, and other unpredictable results. This 
option places heavy responsibility on each user 
sharing the data set. 

4 

specifies that the data set can be fully shared 
by any number of users and buffers used for 
direct processing are refreshed for each request. 

This option requires the program to use the ENQ 
and DEQ macros to maintain data integrity while 
sharing the data set. Improper use of the ENQ 
macro can cause problems similar to those 
described under SHAREOPTIONS 3. (For information 
on using ENQ and DEQ, see System Macros and 
Eg.cilit j .e s .) 

specifies the amount of sharing allowed among systems. 
Job steps of two or more operating systems can gain 
access to the same VSAM data set regardless of the 
disposition specified in each step's DD statement for 
the data set. 

To get exclusive control of the data set's volume, a 
task in one system issues the RESERVE macro. The 
level of cross-system sharing allowed by VSAM applies 
only in a multiple operating system environment. The 
values that can be specified are: 

1 

Reserved 

2 

Reserved 

3 

specifies that the data set can be fully shared. 
With this option, each user is responsible for 
maintaining both read and write integrity for the 
data the program accesses. 

User programs that ignore write integrity 
guidelines can cause VSAM program checks, 
uncorrectable data set failures, and other 
unpredictable results. This option places heavy 
responsibility on each user sharing the data set. 

4 

specifies that the data set can be fully shared. 
Buffers used for direct processing are refreshed 
for each request. 

This option requires that you use the RESERVE and 
DEQ macros to maintain data integrity while 
sharing the data set. (For information on using 
RESERVE and DEQ, see 5.yg±e.m.,M,a 
Facilities .) Writing is limited to PUT-update 
and PUT-insert processing that does not change 
the high used RBA if your program opens the data 
set with DISP=SHR. 

Data set integrity cannot be maintained unless 
all jobs accessing the data set in a cross-system 
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environment specify DISP=SHR. Improper use of 
the RESERVE macro can cause problems similar to 
those described under SHAREOPTIQNS 3. 

Abbreviation: SHR 

STAGE|BIND ICYLINDERFAULT 

specifies how a data or index component that is stored on a 
mass storage volume is to be staged. 

These parameters can be specified only for the data or 
index component of a cluster or alternate index. 

STAGE 

indicates that the component is to be staged from mass 
storage to a direct access storage staging drive when 
the component is opened. 


BIND 

indicates that the component is not only to be staged, 
but also bound (or retained) on the direct access 
storage staging drive until it is closed. 

CYLINDERFAULT 

indicates that the component is not to be staged when 
it is opened, but that data from it is to be staged as 
the processing program needs it. 

Abbreviation: CYLF 

TO ( date ) 1 FOR( davs ) 

specifies the retention period for the entry being altered. 

These parameters cannot be specified for the data or index 
components of clusters, alternate indexes, or catalogs. In 
the case of a non-VSAM data set the expiration date in the 
catalog will be updated, but the expiration date in the 
format-1 DSCB will not be changed. 

TOCdaie) 

specifies the date, in the form yyddd, where yy is the 
year and ddd is the number (001 through 365) of the 
day through which the entry is to be kept. 

FOR(^ays) 

specifies the number of days for which the entry is to 
be kept. The maximum number that can be specified is 
9999. 

If the number specified is 0 through 1830, the cluster 
is retained for the number of days specified; if the 
number is between 1831 and 9999, the cluster is 
retained through the year 1999. 


can be expressed in decimal (n), hexadecimal 
(X'n 1 ), or binary (B f n f ) form. 

UNIQUEKEY[NONUNIQUEKEY 

specifies whether the alternate-key value can be found in 
more than one of the base cluster f s data records. 

UNIQUEKEY 

specifies that each alternate-key value is unique. If 
the same alternate-key value is found in more than one 
of the base cluster*s data records, an error results. 

UNIQUEKEY can be specified only for an empty alternate 
index (that is, an alternate index that is defined but 
not yet built). 

Abbreviation: UNQK 
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NONUNXQUEKEY 

specifies that a given alternate-key value might point 
to more than one data record in the cluster. 
NONUNIQUEKEY can be specified for an alternate index 
at any time. 

If the alternate index is empty, you should also 
consider specifying RECORDSIZE to ensure that each 
alternate index record is large enough to contain more 
than one data record pointer. 

Abbreviation: NUNQK 

UPDATE I NOUPDATE 

specifies whether a base cluster's alternate index upgrade 
set is to be allocated when the path's name is allocated. 

UPDATE 

specifies that the cluster's alternate index upgrade 
set is to be allocated when the path's name is 
allocated with a DD statement. 

Abbreviation: UPD 

NOUPDATE 

specifies that the cluster's alternate index upgrade 
set is not to be allocated but the path's cluster is 
to be allocated. 

Note: If the path is opened specifying NOUPDATE and 

sharing a control block structure which specifies 
UPDATE, the upgrade set has been allocated and the 
upgrade set may be updated. 

Abbreviation: NUPD 

UPDATEPW( password ) 

specifies an update password for the entry being altered. 
Abbreviation: UPDPW 
UPGRADE|NOUPGRADE 

specifies whether an alternate index is to be upgraded 
(that is, kept up to date) when its base cluster is 
modified. 

UPGRADE 

specifies that the cluster's alternate index is 
upgraded (to reflect the changed data) whan the 
cluster's records are added to, updated, or erased. 

If UPGRADE is specified when the cluster is open, the 
upgrade attribute does not apply to the alternate 
index until the cluster is closed and then opened 
(that is, a new set of VSAM control blocks describes 
the cluster and its attributes). 

UPGRADE can be specified only for an empty alternate 
index (that is, an alternate index that is defined but 
not built). However, the UPGRADE attribute is not 
effective for the alternate index until the alternate 
index is built (see the BLDINDEX command). 

Abbreviation: UPG 

NOUPGRADE 

specifies that the alternate index is not modified 
when its base cluster is modified. NOUPGRADE can be 
specified for an alternate index at any time. 

Abbreviation: NUPG 
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WRITECHECKINOWRITECHECK 

specifies whether a data or index component is to be 
checked by a machine action called write check when a 
record is written into it. 

This parameter may be specified to alter the data or index 
components of a cluster or an alternate index. 

WRITECHECK 

specifies that a record is to be written and then 
read, without data transfer, to test for the data 
check condition. 

Abbreviation: WCK 

NOWRITECHECK 

specifies that a record is to be written only. 
Abbreviation: NNCK 
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ALTER EXAMPLES 


Alter a Cluster f s Attributes: Example 1 

In this example, an ALTER command is used to specify passwords 
for an entry-sequenced (nonindexed) cluster, D5Q.EXAMPLE.ESDS1. 
No password for the cluster is required, because the cluster was 
defined without passwords. 

//ALTER1 JOB 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=A 
//SYSIN DD X 
ALTER - 

D50.EXAMPLE.ESDS1 - 
MASTERPHCDEPT26M) - 
CONTROLPMCDEPT26C) - 
UPDATEPMCDEPT26U) - 
READPMC DEPT26R) - 
AUTH0RIZATI0NCD26AUTH) 

/X 

The ALTER command adds passwords to the entry-sequenced 
cluster's cluster catalog entry. However, the passwords are not 
added to the cluster's data entry. If a user's program supplies 
the cluster's data entry entryname and opens the data component, 
the unauthorized user can access the cluster's data records even 
though the cluster itself is password-protected. 

The ALTER command's parameters are: 

• D50.EXAMPLE.ESDS1, the name of the entry-sequenced cluster. 
It is assumed that an alias entrynamed D50 exists for the 
user catalog D27UCAT2. The data set name, 

D50.EXAMPLE.ESDS1, causes the ALTER request to be directed 
to D27UCAT2. 

• MASTERPM, CONTROLPM, UPDATEPM, READPN, and AUTHORIZATION, 
specify passwords and the entryname of the 

usei—security-verification routine. 


Alter the Entrynames of Generically Named Clusters: Example 2 

In this example, several clusters with similar names, 

GENERIC.X.BAKER (where "X" is any 1- to 8-character simple 
name), are renamed so that their entrynames are GENERIC.X.ABLE. 
The name "GENERIC.X.BAKER” is called a generic name. 


//ALTER2 

JOB 

... 

//JOBCAT 

DD 

DSNAME=USERCAT4,DISP=SHR 

//STEP1 

EXEC 

PGM=IDCAMS 

//SYSPRINT 

DD 

SYS0UT=A 

//SYSIN 

DD 

X 

ALTER 

- 



GENERIC.X.BAKER - 
NEWNAMECGENERIC.X.ABLE) 

/x 

Job control language statement: 

• JOBCAT DD, which makes a catalog available for this job: 
USERCAT4. 

The ALTER command changes each generic entryname, 

GENERIC.x.BAKER, to GENERIC.X.ABLE. Its parameters are: 

• GENERIC.x.BAKER, which identifies the objects to be 
modified. 

• NEWNAME, which specifies that each generic entryname 
GENERIC.x.BAKER is changed to GENERIC.X.ABLE. 
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Alter the Attributes of a Generation Data Group: Example 3 

In this example, the attributes of a generation data group are 
modified. Because the attributes of the group are cataloged in x 
the generation data group*s base catalog entry, only this entry 
is modified. 

//ALTER3 JOB 
//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYS0UT=A 

//SYSIN DD X 

ALTER - 

GDG01 - 
NGEMPTY - 
SCRATCH 
/X 

The ALTER command modifies some of the attributes of generation 
data group GDG01. Its parameters are: 

• GDG01, which identifies the object to be modified. 

• NOEMPTY, which specifies that only the oldest generation 
data set is to be uncataloged when the maximum number of 
cataloged generation data sets is exceeded. 

• SCRATCH, which specifies that the generation data set*s DSCB 
is to be removed from the volume's VTOC when the data set is 
uncataloged. 

The attributes specified for the generation data group with the 
ALTER command override any attributes previously specified for 
the GDG. 


ff 

X, 
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BlftlMREX 


The BLDINDEX command builds alternate indexes for existing data 
sets. The format of this command is: 


BLDINDEX 













■iRSTTni'm j i t,«■■ 4 


CWORKFILESCddname ddname)3 


CCATAL0G(catname[/password3)3 


BLDINDEX can be abbreviated: BIX 


BLDXNDEX PARAMETERS 


Required Parameters 


INFILE3 I INDATASET( mt.ry. nam e C/gcjs s wor.cl 3) 

names the DD statement or data set that identifies the base 
cluster or a path that points to the base cluster. 

INFILEC jddn a me C /gassmc d 3 3 

specifies the DD statement that identifies the base 
cluster or a path that points to the base cluster. 

The base cluster must be defined in the same catalog 
as the alternate index, and must contain at least one 
data record. 

p a ss wor d 

If the base cluster or path is password 
protected, supply the read (or highei—level) 
password of the object named in the DD statement. 
If you don't supply the password, the operator or 
TSO terminal user will be prompted to supply the 
correct password. RACF: The read or higher RACF 
authority of the object named in the DD statement 
is required. 

Abbreviation: IFIL E 

IND ATASET (j m lcy nam a C /Ras. ^ .wor.d 3) 

names the data set that identifies the base cluster or 
a path that points to the base cluster. The base 
cluster must be defined in the same catalog as the 
alternate index, and must contain at least one data 
record. 

If the base cluster or path is password 
protected, you supply the read (or highei—level) 
password of the named object. Otherwise, the 
operator or TSO terminal user will be prompted to 
supply the correct password. RACF: The read or 
higher RACF authority of the named objects is 
required. 

When you specify INDATASET, an attempt is made to 
dynamically allocate the base cluster's volume. 
Therefore, the base cluster's volume must be mounted 
as permanently resident or reserved. 

Abbreviation: IDS 
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OUTFILE C ddname I / password 33 IOUTDAT ASET (C 33 

names the DD statement or data set that identifies the 
alternate index or a path that points to the alternate 
index. You can build more than one alternate index for the 
same base cluster by specifying more than one ddname or 
data set name with the OUTFILE or OUTDATASET parameter. 

OUTFILE(.ddname l /p.a,&S&gLCd3 l MganmE/password3 . •. 3 3 
specifies the DD statement that identifies the 
alternate index or a path that points to the alternate 
index. The alternate index must be defined in the 
same catalog as the base cluster, and must be empty 
(that is, its high-used RBA equals zero) or defined 
with the REUSE attribute. 

The alternate index must be related to the base 
cluster identified with INDATASET or INFILE. 

pjag,SMfl.c.ri 

If the alternate index or path is password 
protected, supply the update- or highei—level 
password of the object named in the DD statement. 
If you don’t supply the password, the operator or 
TSO terminal user will be prompted to supply the 
correct password. RACF: The update or higher 
RACF authority of the named object is required. 

Abbreviation: OFILE 

OUTDATASET( entrvname C/ password 3 i . ^p Ar.y,na m ^ l /JE& gg & g jld3...33 
specifies the data set that identifies the alternate 
index or a path that points to the alternate index. 

The alternate index must be defined in the same 
catalog as the base cluster, and must be empty (that 
is, its high-used RBA equals zero) or must have been 
defined with the REUSE attribute. 

The alternate index must be related to the base 
cluster identified with INDATASET or INFILE. 

msswp.rd 

If the alternate index or path is password 
protected, you supply the update- or highei—level 
password of the named object. Otherwise, the 
operator or TSO terminal user may be prompted to 
supply the correct password. RACF: The update or 
higher RACF authority for the named object is 
required. 

When you specify OUTDATASET, an attempt is made to 
dynamically allocate the alternate index’s volume. 
Therefore, the volume must be mounted as permanently 
resident or reserved. 

Abbreviation: ODS 


Optional Parameters 


catalog C s a ln am s l / p .a s s.v(Qjcjd 33 

names the catalog that the work files are to be defined in. 
The work files are defined and used by the BLDINDEX 
routine. 

When all alternate indexes are built and the work files are 
no longer needed by the BLDINDEX routine, they are deleted. 
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If the catalog is password protected# supply its 
update- or highei—level password. If you don*t supply 
the password# the operator will be prompted to supply 
the correct password. RACF: The update or higher RACF 
authority to the catalog is required. 

For information about the order in which a catalog is 
selected when the CATALOG parameter is not specified# see 
"Order of Catalog Selection for BLDINDEX" on page 15. 

Abbreviation: CAT 

EXTERNALSORTI IN TERNA L S! 

specifies whether the key-pointer pairs are to be sorted 
entirely within virtual storage. 

EXTERNALSORT 

specifies that two external sort work files will be 
defined and built as entry-sequenced clusters. You 
must provide two DD statements that describe the 
external sort work files to be defined by BLDINDEX. 

You can name the DD statements IDCUT1 and IDCUT2. 

When you choose other names for the work file DD 
statements# you must identify those DD statements with 
the WORKFILES parameter. 

INTERNALSORT 

specifies that access method services will sort the 
key-pointer pairs entirely within the usei—provided 
virtual storage if possible. 

If not enough virtual storage is provided when you 
specify INTERNALSORT# two external sort work files are 
built and the key-pointer pairs are sorted externally. 
In this case# you must provide DD statements as for 
EXTERNALSORT. 


If the minimum amount of virtual storage is not 

provided (see V SAM .fl rim P Q J 6 m L4p)/ the BLDINDEX 

processing terminates with an error message. 

Abbreviations: ESORT and ISORT 

WORKFILES (ddname ddramai 

names the DD statements that identify the work files you 
want BLDINDEX to define if an external sort of the 
key-pointer pairs is required. 

You can use DD statements to describe two work files that 
will be defined and opened before the BLDINDEX routine 
begins processing the base cluster*s data records. 

When you code the DD statements that describe the work 
files and identify them with the standard ddnames# IDCUT1 
and IDCUT2# you do not need to specify the WORKFILES 
parameter. 

For information on how to code the DD statements that 
describe the work files# see "DD Statements that Describe 
the SORT Workfiles" in VSAM Administration Guide . 

Abbreviation: WFIL E 
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BLDZNDEX EXAMPLE 


Build an Alternate Index Over a Key-Sequenced Data Set: Example 1 

This example builds an alternate index over a previously defined 
base cluster, EXAMPLE.KSDS2. Data records have already been 
loaded into the base cluster, so that it is not empty. The 
alternate index, its path, and its base cluster are all defined 
in the same catalog, USERRCAT. 

//BUILDAIX JOB ... 

//STEPCAT DD DSNAME=USERRCAT,DISP=SHR 

//BASEDD DD DSNAME=EXAMPLE.KSDS2,DISP=OLD 

//AIXDD DD DSNAME=EXAMPLE.AIX,DISP=0LD 

//IDCUT1 DD DSNAME=SGRT.WORK.ONE,DISP=0LD,AMP= 1 AMORG*, 

// VOL=SER=VSER01,UNIT=DISK 

//IDCUT2 DD DSNAME=SORT.WORK.TWO,DISP=OLD,AMP= *AMORG 1 , 

// V0L=SER=V$ERQ1,UNIT=DISK 

//SYSPRINT DD SYS0UT=A 

//SYSIN DD * 

BLDINDEX INFILE(BASEDD) - 

OUTFILECAIXDD/AIXUPPW) - 
CATALOGCUSERRCAT/USER) 

/x 

Job control language statements: 

• STEPCAT DD, which describes the catalog. 

• BASEDD DD, which describes the base cluster. 

• AIXDD DD, which describes the alternate index. 

• IDCUT1 and IDCUT2 DD, which describe a volume containing 
VSAM data space to be made available to BLDINDEX for 
defining and using two sort work data sets in the event an 
external sort is performed. This data space will not be 
used by BLDINDEX if enough virtual storage is available to 
perform an internal sort. If multiple volumes are involved, 
a maximum of five volumes for each work file can be 
specified. 

The BLDINDEX command builds an alternate index. The assumption 
is made that enough virtual storage will be available to perform 
an internal sort. However, note that DD statements with the 
default ddnames of IDCUT1 and IDCUT2 have been provided for two 
external sort work data sets in the event that the assumption is 
incorrect and an external sort must be performed. 

The BLDINDEX command , s parameters are: 

• INFILE, which names the base cluster. The ddname of the DD 
statement for this object must be identical to this name. 
Note that a password is not required, because the base 
cluster is not protected. 

• OUTFILE, which names the alternate index. The ddname of the 
DD statement for this object must be identical to this name. 
The update password of the alternate index is also required. 

• CATALOG, which identifies the user catalog. If it is 
necessary for BLDINDEX to use external sort work data sets, 
they will be defined in and deleted from the catalog. The 
update password will permit these actions. 
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CHKLIST 


smusi 


The CHKLIST command lists tape data sets that were opened during 
a checkpoint. The format of this command is: 


CHKLIST 


INFILE(ddnams) 

C CHECKID (p h .Q- £k i. d * • >) I 
EOUTFlLECddnam^)! 


CHKLIST can be abbreviated: CKLST 


CHKLIST PARAMETERS 

Required Parameter 


INFILEIjMmjmI 

specifies the name of the DD statement that identifies the 
checkpoint data set that contains the checkpoint entries to 
be processed. 

Abbreviation: I FIL E 


Optional Parameters 


CHECKIDEpl^pKijd-..) 

specifies one or more checkpoint identifiers of entries in 
the checkpoint data set. These entries contain names of 
tape data sets that were open at the time of the 
checkpoint. 


jc h ecki d 

checkid must be 1 to 16 characters in length. 


The checkid must be the same as was specified in the 
CHKPT macro. A maximum of 255 checkids can be 
specified. Multiple checkids may be specified in any 
sequence. 


If the checkpoint data set contains duplicates of a 
checkid, you can cause all the checkpoint entries with 
that checkid to be listed: 


• By specifying the checkid at least twice 

• By specifying, along with the checkid, a checkid 
for which there is ng entry in the checkpoint data 
set 


If you do neither, only the first checkpoint entry 
found with the checkid is listed. 


If CHECKID is omitted, the identifications of tape data 
sets that were open at the time of a checkpoint are listed 
for all entries in the checkpoint data set. 

CHECKID must be omitted when a member of a partitioned 
checkpoint data set has been specified after ddname in the 
DD statement identified by INFILE. 

Abbreviation: CH KID 
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CHKLIST 


OUTFILEt ddname ) 

specifies the ddname of the DD statement that identifies j 
data set other than the SYSPRINT data set to be used as a 
target data set. 

A target data set must meet the requirements shown under 
"For a Target Data Set" on page 10. If OUTFILE is not 
specified, the tape data set information is listed in the 
SYSPRINT data set. 

Abbreviation: OFILE 
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CHKLZST 


CHKLXST EXAMPLES 


Selecting Specific Checkpoint Entries: Example 1 

In this example, the tape data sets that were open at checkpoint 
time are identified and listed on SYSPRINT for checkpoint 
entries C0000001 and CQ00Q002. 


//CHKLISTl 

JOB 

... 

//STEP1 

EXEC 

PGM=IDCAMS 

//SYSPRINT 

DD 

SYSOUT=A 

//CHKPT 

DD 

DSN=CHKPT.DATASET,DISP=0LD 

//SYSIN 

DD 

X 

CHKLIST 

- 



INFILECCHKPT) - 
CHECKIDCCQQ00001 C0000002) 

/X 

Job control statement: 

• CHKPT DD, which identifies the checkpoint data set that 
contains the entries for which the tape data set information 
is to be listed. 

The CHKLIST command prints the tape data set information as 

specified by the command f s parameters: 

• INFILE, which points to the CHKPT DD statement. The CHKPT 
DD statement identifies the checkpoint data set. 

• CHECKID, which specifies that the checkpoint entries with 
checkids C0000001 and C0000002 are the only ones on the 
checkpoint data set for which the tape data set information 
is to be listed. 

The output shown in Appendix C, "Sample Output from CHKLIST" on 

page 315 was obtained with this JCL. 


Processing a Member of a Partitioned Checkpoint Data Set: Example 2 

In this example, the checkpoint data set is a partitioned data 
set, and member C0000001 is selected for processing by CHKLIST. 

//CHKLIST2 JOB 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYSQUT=A 

//CHKPTDD DD DSN=EXAMPLE.CHKPTDS2CCOO00001), 

// DISP=SHR 
//SYSIN DD X 

CHKLIST - 

INFILE(CHKPTDD) 

/x 

Job control language statement: 

• CHKPTDD DD, which identifies the partitioned checkpoint data 
set and the specific member for which the tape data set 
information is to be listed. 

The CHKLIST command prints the tape data set information as 
specified by its parameter, INFILE, which points to the CHKPTDD 
DD statement. The CHKPTDD DD statement identifies the member of 
the partitioned checkpoint data set. 

The CHECKID parameter is omitted, so the checkpoint entry 
C0000001 will automatically be processed by CHKLIST. 
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CNVTCAT 

ciiy.Tc&i 


The CNVTCAT command converts OS CVOL entries into VSAM catalog 
entries. The format of this command is: 


CNVTCAT 

CINFILElddnarnsJI 


INDAT AS et (sji±cyjia.ro.e )} 


COUTFILEf .drirtsua,SE /password]) | 


OUTDATASETCentrvnameE/passwordl)1 


CATALOG (fiaAnams t /password 3)} 


[CVOLEQUATESt(catname (volser 


I Yfilssc...]))[ Csainams.3)3 


IUSII NOLIST] 


E mast E RCATALOG (ps^inama E /pas.swQrd ]) ] 


CNVTCAT can be abbreviated: CNVTC 


CNVTCAT PARAMETERS 


Required Parameters 


INFILECddmme) I INDATASET( entrvname ) 

specifies the name of a DD statement or an alias entryname 
for an OS CVOL to be converted to a VSAM catalog. 

INFILECridpamfl) 

specifies the name of a DD statement for an OS CVOL 
that is to be converted. 

ddnamfi 

specifies the name of the DD statement that identifies 
the OS CVOL that is to be converted. 

Abbreviation: IFIL E 

IND AT AS ET ( e plny mm wo r d I 

specifies the alias entryname (in the master catalog) 
of the OS CVOL that is to be converted. 

If INDATASET is specified, an attempt is made to 
dynamically allocate the OS CVOL. The OS system 
catalog entryname, SYSCTLG, cannot be specified. 

Abbreviation: IDS 

jm-tny name 

names the entry to be converted. 

OUTFILE (. ddparos i vw . r. d 3) IOUTDAT ASET ( entrvname i / password ! ) I 

CAT A LOG ( t /Pi US aw. Q JC d 3 ) 

identifies the VSAM catalog to receive the converted OS 
CVOL entries. 

OUTFI LE (ddaamg C /p asswo r d 3) 

specifies the name of a DD statement that identifies 
the target VSAM catalog. 

ri doamg 

identifies the VSAM target catalog. 

jeaaBaaed 

specifies the update- or higher-level password for a 
password-protected catalog. RACF: The update or 
higher RACF authority to the catalog is required. 

Abbreviation: OFILE 


56 


MVS/XA VSAM Catalog: Access Method Services Reference 





CNVTCAT 


OUTDATASET (.e M ryn a me t /ga ssw Qiid 1) 

specifies the name of the VSAM target catalog. If 
OUTDATASET is specified, an attempt is made to 
dynamically allocate the catalog. 

je.n- t jcy.n a .rti e 

names the target VSAM catalog. The alias name of the 
catalog will not be accepted. 

m sS MO J ld 

specifies the update- or highei—level password for a 
password protected catalog. RACF: The update or 
higher RACF authority to the catalog is required. 

Abbreviation: ODS 

CATALOG (.c a tn a me [ jcd 3) 

specifies the name of a catalog that is to receive the 
converted entries. The alias name of the catalog will 
not be accepted. 

jeassKond 

specifies the update- or highei—level password for a 
password-protected catalog. RACF: The update or 
higher RACF authority for the catalog is required. 

Abbreviation: CAT 


Optional Parameters 


CVOLEQUATESC (salaams (yolssrC yelssr*• .3]))C ( ca in am e, ..)] 
identifies the user catalog that converted control volume 
pointer entries (CVPEs) point to. 

CVPEs point to OS CVOLs that contain entries. The entries 
in an OS CVOL might have been (or might soon be) converted 
to VSAM catalog entries. 

When a CVPE is converted to an alias entry, the alias entry 
points to the user catalog that contains (or is to contain) 
the OS CVOLs converted entries. 

When you specify CVOLEQUATES, you must also specify 
MASTERCATALOG. 

specifies the name of an existing VSAM catalog. The 
catalog named contains or is to contain converted OS 
CVOL entries that were cataloged in the OS CVOL 
pointed to by the CVPE being converted. 

yjp l sa r . 

specifies the volume serial number(s) of one or more 
OS CVOLs for which entries have been or are to be 
converted. 

Abbreviation: CV EQU 

LIST I NOLIST 

specifies whether entries are to be listed. 

LIST 

specifies that entries are to be listed after they are 
converted. 

NOLIST 

specifies that entries are not to be listed after they 
are converted. 

Abbreviation: N LIST 
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CNVTCAT 


MASTERCATALOG t£3-tD £ m£ t /g a £ S HQ.Ld 3 ) 

specifies the name of the master catalog into which any 
aliases for user catalogs are to be placed. MASTERCATALOG 
is required when CVOLEQUATES is specified. 

password 

specifies the master catalog's update- or higher-level 
password. 

Abbreviation: MCAT 


CNVTCAT EXAMPLES 


The two CNVTCAT examples are related and show how the entries of 
two OS CVOLs in a system can be converted to entries in a 
catalog. The OS CVOL on volume VSER09 contains control volume 
pointer entries (CVPEs) that point to the OS CVOL on volume 
VSER08. Therefore, the two OS CVOLs are chained together with 
VSER08's OS CVOL at the end of the chain. When two or more OS 
CVOLs are chained together, the OS CVOL at the end of the chain 
should be converted first. 


Convert OS CVOL Entries to Entries in a VSAM Catalog: Example 1 

In this example, the entries in the OS CVOL on volume VSER08 are 
converted to catalog entries and written into the USER11 
catalog. 

//CNVTCAT1 JOB 

//STEP1 EXEC PGM=IDCAM5 

//SYSPRINT DD SYS0UT=A 

//0SCAT1 DD V0L=SER=VSERQ8,DISP=0LD,DSN=SY$CTLG, 

// UNIT=DISK 
//SYSIN DD X 

CNVTCAT - 

INFILEC0SCAT1) - 
CATAL0GCUSER11/MR) 

/X 

Job control language statement: 

• 0SCAT1 DD, which describes and allocates the OS CVOL that is 
to be converted. 

The CNVTCAT command converts the entries in the OS CVOL on 
volume VSER08 to entries in a user catalog, USER11. The 
command's parameters are: 

• INFILE, which points to the 0SCAT1 DD statement. 

• CATALOG, which specifies the name of an existing catalog, 
the user catalog USER11. USER11 is to receive the converted 
entries. The user catalog's update- or highei—level 
password, MR, is required if passwords are used. 


\ . 
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CNVTCAT 


Convert an OS CVOL Having Control Volume Pointer Entries: Example 2 

In this example, the entries in the OS CVOL on volume VSER09 are 
converted to catalog entries and written into the USER12 
catalog. Some of the entries in the OS CVOL are control volume 
pointer entries, and point to the OS CVOL on volume VSER08 
(which was converted in the previous example). 

//CNVTCAT2 JOB 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYS0UT=A 

//0SCAT2 DD VOL=SER=VSER09,DISP=0LD,DSN=SYSCTLG, 

// UNIT=DISK 
//SYSIN DD X 

CNVTCAT - 

INFILEC0SCAT2) - 
CATAL0GCUSER12/MR) - 
CVOLEQUATESC - 

(USER11 (VSER08)) ) - 

NOLIST - 

MASTERCATALOGCAMASTCAT) 

/x 

Job control language statement: 

• 0SCAT2 DD, which describes and allocates the OS CVOL that is 
to be converted. 

The CNVTCAT command converts the entries in the OS CVOL on 
volume VSER09 to entries in a user catalog, USER12. Because 
CVOLEQUATES is specified, an alias entry is built and put in the 
master catalog to relate the name VSER08 to the user catalog 
USER11. The command’s parameters are: 

• INFILE, which points to the 0SCAT2 DD statement. 

• CATALOG, which specifies the name of an existing catalog, 
the user catalog USER12. USER12 is to receive the converted 
entries. The user catalog’s update- or highei—level 
password, MR, is required if passwords are used. 

• CVOLEQUATES, which specifies that control volume pointer 
entries (CVPEs) are to be converted to alias entries. Each 
CVPE in VSER09’s OS CVOL points to an entry in VSER08’s OS 
CVOL. Each new alias entry points to the USER11 user 
catalog connector entry in the master catalog. The alias 
entries are written into the master catalog. 

• NOLIST, which specifies that the entries are not to be 
listed after they are converted. 

• MASTERCATALOG, which identifies the master catalog. This 
parameter must be specified because CVOLEQUATES is also 
specified. If the master catalog is password-protected, the 
catalog’s update- or highei—level password must be 
specified. 
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DEFINE ALIAS 

DE FI NE ALI AS 


The DEFINE ALIAS command defines an alternate name for a f' : 
non-VSAM data set or a user catalog. The format of this command \ 
is: 


DEFINE 

ALIAS 


CNAMECaliasnsjnfi) 


RELATE (fininyoatas J) 


[ CATALOG (£ / passwa rd J) 1 


DEFINE can be abbreviated: DEF 


DEFINE ALIAS PARAMETERS 


Required Parameters 


ALIAS 

specifies that an alias for a user catalog or non-VSAM data 
set is to be defined. 

NAME(aliasmmfi) 

specifies the alias (the alternate entryname) for a user 
catalog or non-VSAM data set. An alias must be unique 
within a catalog. 

RELATE () 

specifies the name of the entry (the user catalog entryname 
or the non-VSAM data set name) for which the alias is being 
defined. 

An alias entry must reside in the same catalog as the entry 
to which it is related. When an alias is defined, catalogs 
are searched for the related entry. When the related entry 
is found, the alias entry is added to the catalog. 

Abbreviation: REL 


Optional Parameter 


catalog ( .c a Id sim I/eassMa rd 3 ) 

identifies the catalog in which the alias is to be defined. 

If the catalog's volume is physically mounted, it is 
dynamically allocated. The volume must be mounted as 
permanently resident or reserved. For information about 
the order in which a catalog is selected when the catalog's 
name is not specified, see "Order of Catalog Selection for 
DEFINE" on page 16. 


specifies the name of the catalog. When the alias is 
for a user catalog connector, catname is the name of 
the master catalog. 

gass w & rd 

specifies a password. If the catalog is password 
protected, supply the catalog's update- or 
highei—level password. If you don't supply the 
password, the operator or TSO terminal user will be 
prompted to supply the correct password. RACF: The 
update or higher RACF authority to the catalog is 
required. 

Abbreviation: CAT 


1 

X. 
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DEFINE ALIAS 


DEFINE ALIAS EXAMPLES 


Define an Alias for a Non-VSAM Data Set: Example 1 

In this example, an alias is defined for a non-VSAM data set. 


//DEFALS 

JOB 

... 

//STEP1 

EXEC 

PGM=IDCAMS 

//STEPCAT 

DD 

DSNAME=USERCAT4,DISP=0LD 

//SYSPRINT 

DD 

SYS0UT=A 

//SYSIN 

DD 

X 


DEFINE ALIAS - 

(NAMECEXAMPLE.NQNVSAM1) - 
RELATE(EXAMPLE.NONVSAM) ) - 
CATAL0GCUSERCAT4/USERMRPW) 

/x 

Job control language statements 

• STEPCAT DD, which makes a catalog available for this job 
step: USERCAT4. 

The DEFINE ALIAS command defines an alias, EXAMPLE.N0NVSAM1, for 

the non-VSAM data set EXAMPLE.NONVSAM. Its parameters are: 

• NAME, which specifies the alias (alternate entryname), 
EXAMPLE.N0NVSAM1. 

• RELATE, which specifies the name that the alias is an 
alternate entryname for, EXAMPLE.NONVSAM. 

• CATALOG, which supplies the update password of the user 
catalog. 


Define an Alias for a User Catalog: Example 2 

In this example, an alias is defined for a user catalog. The 
alias is defined in the master catalog. 

//DEFUCALS JOB 
//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYS0UT=A 
//SYSIN DD x 
DEFINE ALIAS - 

(NAMECD4Q) - 
RELATECD27UCAT1)) - 
CATALOGCAMAST1/MASTUPW1) 

/x 

The DEFINE ALIAS command defines an alias, D40, for the user 
catalog, D27UCAT1. Any data set defined in D27UCAT1 having 
f D40 f as its first qualifier will be located by VSAM in D27UCAT1 
when it is referred to in an access method services command or 
user program without requiring a JOBCAT or STEPCAT DD statement 
for D27UCAT1. D27UCAT1 can also be referred to using the alias 
D40. The parameters are: 

• NAME, which specifies the alias, D40. 

• RELATE, which specifies the name of the user catalog for 
which D40 is an alternate entryname (alias). 

• CATALOG, which supplies the update password of the master 
catalog. 
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DEFINE ALTERNATEINDEX 

DEFINE.ALTE R NA TE INDEX 


The DEFINE ALTERNATEINDEX command defines an alternate index. 

When you use this command, you can specify attributes for the \ £ 

alternate index as a whole and for the components of the 
alternate index. The format of the DEFINE ALTERNATEINDEX 
command is: 

DEFINE ALTERNATEINDEX (parameters) - 
[DATACparameters)3 - 
[INDEX!parameters)] - 
CCATALOG(subparameters)] 


DEFINE 


ALTERNATEINDEX 

(NAME(e nt ryn ame ) 

RELATE! e ntr yname^passwo r d l) 
{CYLINDERS! primary l sssoadary])I 

records tErimaryI s econds ey 3)1 

TRACKS (jEcimaryE s e co nda ry! )3 
VOLUMES(yplsect y_alssji.»«I) 

[ ATTEMPTS (nUfflkSE 12)1 

[AUTHORIZATION! entrvpoint [ string !)3 
IBUFFERSPACE( size )1 
[CODE! code )3 

[CONTROLINTERVALSIZE( size )] 
[CONTROLPW! password )1 
IDESTAGEWAITI NODESTAGEWAIT ] 

[ERASE I NOERASE ] 

[EXCEPTIONEXITC entrypoint n 

[FILE( ddname )3 

[FREESPACEt Cl-percent ! CA-Percent ]10 
[IMBED I NOINBED ] 

[ KEYRANGES ((loyto h i. gh k SY ) 

t (lanksY hisfaksY)-••3)3 
[KEYSCianaih aifaailM £)1 
[masterpw( p ass w o rd)I 

[MODEL! entrvname [/ password 3 
I catname [/ password !1)3 
[ORDERED I UNORDEREP 1 
[QWNER[p w n s r ld )3 

[READPW! password }3 
[RECORDSIZE! average maximum I 

M£6 HMD)] 

[REPLICATEINPREPIICAIE3 
[REUSE I NOREUSE 3 
[SHAREOPTIONS! crossregion 
[ crosssvstem l11 3)3 
[SPEED I RECOVERY ! 

[ STAGE |BIND|CYLINDERFAULT3 
[TO(dais)I FOR(days)3 
[UNIQUE ISU BALL0CATI0N 3 
[ UNIQUEKEY | NfiN.OMMME.Yl 
[UPDATEPH! password )3 
[ UP G RA D E I NOUPGRADE3 

iwritecheckin owri t eph ec k i) 


fi)3 


(Continued on next page.) 


£ 

V 
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[DATA 

([ATTEMPTS!number)! 

[AUTHORIZATIONentrypoint[ string])1 

[BUFFERSPACElsize ) 1 

[C0DE(£2de)l 

[CONTROLINTERVALSIZElsize) I 
[CONTROLPW(password )] 

[CYLINDERS!primary! secondary] ) 1 

RECORDS!primary! secondary] ) 1 

TRACKS(primary! secondary] )1 
[DESTAGEWAIT | NODESTAGEMAIT1 
[ ERASE | NOERASE] 

[EXCEPTiONEXiT(entryppint)] 

[FlLE!ddoams)] 

[FREESPACE!Cl-percent! CA-percentl )] 

[KEYRANGES! (JLowKey highly) 

! (laMiiey highkey ) ♦. ♦ 1)] 

[KEYSdegaih q£±sm±U 
[MASTERPW!password)] 

[ MODEL(entrynamel/password! 

[ catnamat^pasgwprd]] )J 
[ NAME!entrvname )] 

[ ORDERED|UNORDERED ] 

[ OWNER ( jaansrid) 1 

EREADPWEpassword)3 
[RECORDSIZE!average maxjjnum) ] 

! REUSE|NOREUSEI 

! SHAREOPTIONS!g.cPs.sJiagiflD ! crosssvsteml )] 

[SPEED|RECOVERY] 

[STAGE|BIND|CYLINDERFAULT] 

[UNIQUE|SUBALLOCATION] 

[UNIQUEKEY|NONUNIQUEKEY] 

[UPDATEPW!password) ] 

[ VOLUMES ( voIser [ volser...3)3 
[WRITECHECK | NOWRITECHECK] )] 



[INDEX 

([ATTEMPTS!number)] 

[ authorization !entr.y£.pJLrdL[ string] )] 

[CODE(cpde)] 

[ CONTROLINTERVALSIZE(size) ] 

[ CONTROLPW!password )] 

CCYLINDERSCprimarvE secondsrv3 ) I 

RECORDS(primary! Secondary] ) 1 

TRACKSCprimarvE secondarv3 33 
[DESTAGEWAIT | NODESTAGEWAIT1 
[EXCEPTIONEXIT(entrypoint)] 

[FILE!ddname ) 3 
[ IMBEDINOIMBED] 

[MASTERPW!password ) 3 
[MODEL!entryname!/password] 

[ catname[/password] ]) 3 

ENAME ( entrvname ) 3 
[ORDERED | UNORDERED3 
[ OWNER!ownerid)3 

EREADPWCpassword)3 
[ REPLICATE | NOREPLICATE1 
[REUSE!NOREUSE3 

[ SHAREOPTIONS ! cjio<?sr.ftglP_D [ crosssvsteml ) 3 
[ STAGE I BIND | CYLINDERFAULT] 

[UNIQUE | SUBALLOCATION1 

[ UPDATEPW ( password ) 3 

[VOLUMESIvolser! volser...])] 

[WRITECHECK | NOWRITECHECK] )] 

[ CATALOG (c.a±nanis ! /password ]) ] 


DEFINE can be abbreviated: DEF 
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DEFINE ALTERNATEXNDEX 

DEFINE ALTERNATEXNDEX PARAMETERS 


Required Parameters 


ALTERNATEXNDEX 

specifies that an alternate index is to be defined. 

The ALTERNATEINDEX keyword is followed by the parameters 
specified for the alternate index as a whole. These 
parameters are enclosed in parentheses and# optionally# are 
followed by parameters specified separately for the DATA 
and INDEX components. 

Abbreviation: AIX 

NAME C entr y name ) 

specifies the alternate index's entryname or the name of 
each of its components. The entryname specified for the 
alternate index as a whole is not propagated to the 
alternate index's components. 

You can define a separate entryname for the alternate 
index# its data component# and its index component. If no 
name is specified for the data or index component# a name 
is generated. 

When the alternate index# data component# and index 
component are individually named# each can be addressed. 

RE LATE (entrygaae C /JBasSMfiLCd 3 ) 

names the alternate index's base cluster. The base cluster 
is an entry-sequenced cluster or a key-sequenced cluster 
that the alternate index is to be related to. You cannot 
relate an alternate index to a reusable cluster or a 
relative record cluster. 

pasaiaol 

specifies either the base cluster's master password or 
the catalog's master password (that is# the master 
password of the catalog that contains the base 
cluster's entry). 

If no password is specified with either the RELATE or 
the CATALOG parameter# VSAM will ask the operator for 
the base cluster's master password. RACFs The alter 
RACF authority to the base cluster or catalog is 
required. 

Abbreviation: REL 

CYLINDERS(pr imar y[ sec & nd& rxl) | 

RECORDS! primerv C secondary ])I 
TRACKS (pr ima cy.E ) 

specifies the amount of space to be allocated to the 
alternate index from the volume's available space when 
UNIQUE is specified# or from the available space of one of 
the volume's VSAM data spaces. 

Unless you specify the MODEL parameter# you must specify 
one# and only one# of the following parameters: CYLINDERS# 
RECORDS# or TRACKS. 

When you specify UNIQUE# space is always allocated in 
cylinders. If the amount of space you specify for the data 
component of the alternate index is not an even multiple of 
cylinder size# VSAM rounds the allocation upward to a 
multiple of a cylinder. 

If you specify RECORDS# the amount of space allocated is 
the minimum number of tracks that are required to contain 
the specified number of records. However# if you specify 
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DEFINE ALTERNATEINDEX 


TRACKS or RECORDS and the minimum number of tracks exceeds 
a cylinder, space is allocated in terms of cylinders. 

When UNIQUE or REUSE is specified, each volume can contain 
a maximum of 16 extents. 

When the data component is not divided into key ranges and 
more than one volume is specified, the primary amount of 
space is allocated only on the first volume when the 
component is defined. When the component increases in size 
so as to extend on to additional volumes, the first 
allocation on each overflow volume is the primary amount. 

When KEYRANGES is specified and the data component is to be 
contained on more than one volume, the primary amount of 
space is immediately allocated on each volume required for 
the key ranges. If more than one key range is allocated on 
a single volume, the primary amount is allocated for each 
key range. 

Secondary amounts can be allocated on all volumes available 
to contain parts of the alternate index regardless of the 
key ranges when the alternate index is extended. 

You can specify the amount of space as a parameter of 
ALTERNATEINDEX, as a parameter of DATA, or as a parameter 
of both DATA and INDEX. If the space is specified as a 
parameter of: 

• ALTERNATEINDEX, the amount specified is divided between 
the data and index components. The division algorithm 
is a function of control interval size, record size, 
device type, and other data set attributes. 

If the division results in an allocation for the data 
component that is not an integral multiple of the 
required control area size, the data components 
allocation is rounded up to the next higher control 
area multiple. This rounding may result in a larger 
total allocation for your alternate index than that 
which you specified. 

• DATA, the entire amount specified is allocated to the 
data component. An additional amount of space, 
depending on control interval size, record size, device 
type, and other data set attributes, is allocated to 
the index component. 

To determine the exact amount of space allocated to each 
component, list the alternate index’s catalog entry, using 
the LISTCAT command. 

When you specify UNIQUE and the alternate index’s data 
space is the first data space on a volume that belongs to a 
recoverable catalog, one additional cylinder is allocated 
for the catalog recovery area. 

The primary and each secondary allocation must be able to 
be satisfied within five extents; otherwise, your DEFINE or 
data set extension will fail. Primary and secondary can be 
expressed in decimal (n), hexadecimal (X’n’), or binary 
(B 1 n 1 ) form. 

pri mary 

specifies the initial amount of space that is to be 
allocated to the alternate index. 

se c o nda ry 

specifies the amount of space that is to be allocated 
each time the alternate index extends, as a secondary 
extent. When secondary is specified and the alternate 
index is suballocated, space for the alternate index’s 
data and index components can be expanded to include a 
maximum of 123 extents. 
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If the data space that contains all or part of the 

cluster cannot be extended because the cluster f s 

secondary allocation amount is greater than the data 

space's secondary allocation amount, VSAM builds a new \ / 

data space. The new data space's primary and 

secondary allocation amounts are equal to the 

cluster*s secondary allocation amount. 

Abbreviations: CYL, REC, and TRK 

VOLUMESCyjoJLs ar I y. Q l,s.€LC*.. n 

specifies the volume(s) on which an alternate indexS 
components are to have space. 

If you do not specify the MODEL parameter, VOLUMES must be 
specified either as a parameter of ALTERNATEINDEX, or as a 
parameter of both DATA and INDEX. 

If the data and index components are to reside on different 
device types, you must specify VOLUMES as a parameter of 
both DATA and INDEX. If more than one volume is listed 
with a single VOLUMES parameter, the volumes must be of the 
same device type. 

A volume serial number may be repeated in the list only if 
the KEYRANGE parameter is specified. You may want to do 
this in order to have more than one key range on the same 
volume. Even in this case, repetition is only valid if all 
duplicate occurrences are used for the primary allocation 
of some key range. 

In a system with the Mass Storage System, an alternate 
index or component can be defined on a mass storage volume. 

The VOLUMES parameter interacts with other DEFINE 
ALTERNATEINDEX parameters. You should ensure that the r , 

volume(s) you specify for the alternate index are 

consistent with the alternate indexS other attributes: v j 

• SUBALLOCATION: If UNIQUE is not specified, the volume 
must already contain VSAM data space. 

• KEYRANGES: If KEYRANGES and UNIQUE are specified for a 
VSAM catalog, a VSAM data space is built and allocated 
on a separate volume for each key range. 

• ORDERED: If ORDERED is specified, the volumes are used 
in the order listed. If ORDERED and KEYRANGES are 
specified, there is a one-to-one correspondence between 
the key ranges in the key range list and the volumes in 
the volser list. 

• CYLINDERS, RECORDS, TRACKS: The volumeCs) contains 
enough available space to satisfy the components 
primary space requirement. 

• FILE: The volume information supplied with the DD 
statement pointed to by FILE must be consistent with 
the information specified for the alternate index and 
its components. 

• CATALOG: The data space on the volume must be defined 
before the alternate index, and the catalog specified 
must own the volume. 

Abbreviation: VOL 


4 % 
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Optional Parameters 


ATTEMPTS (nyjgfefiJC I Z J 

specifies the maximum number of times the operator can try 
to enter a correct password in response to a prompting 
message. 

This parameter only has effect when the alternate index f s 
master password is not null. A prompting message is issued 
only when the user has not already supplied the appropriate 
password. 

D umbe r 

is an integer from 0 to 7 and can be expressed in 
decimal (n), hexadecimal CX'n'), or binary (B'n') 
form. 


When ATTEMPTS(O) is coded, the operator is not 
prompted and is not allowed to enter a password from 
the console. 


Note to TSO users* At a TSO terminal, the logon 
password is checked first, before the user is prompted 
to supply a password for the alternate index. 

Checking the logon password counts as one attempt to 
obtain a password. If ATTEMPTS is not specified, the 
user has one attempt to supply the alternate index's 
password, because the default is 2. 

Abbreviation* ATT 


AUTHORIZATIONsiring] ) 

specifies that a usei—security-verification routine (USVR) 
is available for additional security verification. When a 
protected alternate index is opened and the user supplies a 
correct password other than the alternate index's master 
password, the USVR receives control. For details on coding 
a USVR, see VS M J Ydm i> 


If a USVR is loaded from an unauthorized library during 
access method services processing, an abnormal termination 
will occur. See "Authorized Program Facility" in VSAM 

Mm i * 

This parameter only has effect when the master password is 
not null. 


je.aAc.yjR.fil.ni 

specifies the name of the USVR. 


aAnlna 

specifies information to be passed to the USVR when it 
receives control to verify authorization. 


Abbreviation: AUTH 


BUFFERSPACE( size ) 

specifies the minimum space that your program's address 
space is to provide for buffers. 

When you specify BUFFERSPACE, you must specify at least 
enough space to contain two data control intervals and one 
index control interval. The buffer space size you specify 
helps VSAM determine the data component's and index 
component's control interval size. If the specified size 
is less than VSAM requires for the buffers needed to run 
your job, VSAM terminates your job and provides an 
appropriate error message. 

When you do not specify BUFFERSPACE, VSAM determines the 
buffer space size. VSAM determines the control interval 
size first, then sets the buffer space amount equal to two 
data control intervals and one index control interval. 
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53LSS 

is the amount of space to be provided for buffers. 

The value can be expressed in decimal (n), hexadecimal 
(X'n'), or binary (B'n 1 ) form, but must not exceed 
16776704. 

Abbreviations: BUFSPC or BUFSP 
CATALOG C fia An a m a C /g as sM fl . c d 3) 

identifies the catalog in which the alternate index is to 
be defined. The catalog also contains the base cluster's 
entry (see the RELATE parameter above). For information 
about the order in which a catalog is selected if the 
catalog's name is not specified, see "Order of Catalog 
Selection for DEFINE" on page 16. 

&a.tnarofi 

specifies the catalog's name. 

Basampd 

specifies the catalog's update- or highei—level 
password. If the catalog is password-protected, you 
must supply the catalog's update- or higher-level 
password. If no password is specified with the 
CATALOG parameter, VSAM will prompt the operator for 
the catalog's update password. RACF: The update or 
higher RACF authority to the catalog is required. 

If the base cluster's master password is not specified 
with the RELATE parameter, the catalog's master 
password must be specified. RACF: The alter RACF 
authority to the catalog is required. 

If the catalog's volume is physically mounted, it is 
dynamically allocated. The volume must be mounted as 
permanently resident or reserved. 

Abbreviation: CAT 

CODEC£fid£) 

specifies a code name for the alternate index. If an 
attempt is made to access a password-protected alternate 
index without first supplying an appropriate password, a 
prompting message will be issued to the operator's console 
(see ATTEMPTS above). The prompting message includes the 
code name, which identifies the alternate index without 
revealing its entryname. 

This parameter only has effect when the alternate index's 
master password is not null. 

If you do not specify a code name for the alternate index, 
the prompting message identifies the alternate index with 
its entryname. 

CONTROLINTERVALSIZE( size ) 

specifies the size of the alternate index's control 
intervals. The size of the control interval depends on the 
maximum size of data records, and on the amount of buffer 
space specified. 

Nhen you do not specify the control interval size, VSAM 
determines the control interval size. If you have not 
specified BUFFERSPACE and the size of your records permits, 
VSAM selects the optimum size for the data control interval 
size and 512 bytes for the index control interval size. 

for the alternate index's data component. 

Because an alternate index always has the spanned 
attribute, the control interval size can be less than 
the maximum record length. The sizes you can specify 
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(between 512 and 32 768 bytes) are integer multiples 
of 512 or 2048s 

CISZ = (n x 512) or (n x 2048) 

where n is a positive integer from 1 to 16. 

When you specify a size that is not a multiple of 512 
or 2048/ VSAM chooses the next higher multiple. 


Si Z& 

for the alternate index's index component. 

You can specify the following values for the index 
component's control interval sizes 

CISZ = [512 | 1024 | 2048 | 40961 

For a discussion of the relationship between control 
interval size and physical block size, refer to "Optimizing 
VSAM Performance" in V. SA M. * The 

discussion also includes restrictions that apply to control 
interval size and physical block size. 

Abbreviations: CISZ or CNVSZ 

CONTROLPW(mSSHOJld) 

specifies a control password for the entry being defined. 

When specified as a parameter of DATA or INDEX/ the control 
password allows the user's program to open the data 
component or index component for read and write processing 
of the component's control intervals (that is, the entire 
control interval/ including the data portion of stored 
records and the control fields VSAM inserts into stored 
records and control intervals). 

If a read or update password is the only password specified 
for the object/ it (the highest-level password) propagates 
upward and becomes the password for all higher unspecified 
levels. 

Abbreviation: CTLPW 
DESTAGEWAIT| NQDESTAGEWAIT 

specifies whether an alternate index or its component that 
is stored on a mass storage volume is to be destaged 
synchronously or asynchronously with respect to the program 
that closes it. 

Note: When the alternate index or component is not stored 

on a mass storage volume/ the attribute is ineffective 
until the direct access storage volume on which the 
alternate index or component is stored is converted to a 
mass storage volume (using the CONVERTV command/ described 
in 

Infor matio n) • 

DESTAGEWAIT 

indicates that destaging is to be completed before 
VSAM returns control to the program that issued the 
CLOSE macro. VSAM can thus notify the program whether 
destaging was successful. 

Abbreviation: DSTGW 

NODESTAGEWAIT 

indicates that notification of unsuccessful destaging 
is to be made only by a message to the operator. 

Abbreviation: NDSTGW 

When one of these parameters is specified for the data 
component and the other parameter is specified for the 
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index components the components are destaged separately as 
specified, unless the sequence set of the index component g- 

is embedded in the data. In that case, the parameter 
specified for the index component applies to both \ 

components. 

erase imebasi 

specifies whether the alternate index data components 
records are to be erased when the alternate index is 
deleted. 

This attribute applies only to the alternate index f s data 
component. 

ERASE 

specifies that the records of the alternate index data 
component are to be overwritten with binary zeros when 
the alternate index is deleted. 

Abbreviation: ERAS 

NOERASE 

specifies that the records of the alternate index data 
component are not to be overwritten with binary zeros. 

Abbreviation: NERAS 

EXCEPTI0NEXIT(^Dltyjp.giQt3 

specifies the name of the usei—written routine, called the 
exception exit routine, that receives control when an 
exceptional I/O error condition occurs during the transfer 
of data between your program's address space and the 
alternate index's direct access storage space. (An 
exception is any condition that causes a SYNAD exit to be 
taken.) 

The component's exception exit routine is processed first, 
then the user's SYNAD exit routine receives control. 

If an exception exit routine is loaded from an unauthorized 
library during access method services processing, an 
abnormal termination will occur. 

Abbreviation: EEXT 

FILECddiiame) 

names the DD statement that identifies the direct access 
deviceCs) and volume(s) on which space is to be allocated 
to the alternate index. 

If more than one volume is specified in a volume list, all 
volumes must be of the same device type. When the data 
component and index component are to reside on separate 
devices, you can specify a separate FILE parameter as a 
parameter of DATA and INDEX to point to different DD 
statements. 

When the alternate index is defined in a recoverable 
catalog, and FILE is specified as a parameter of 
ALTERNATEINDEX, the FILE parameter can identify the DD 
statement for all volumes on which space is to be 
allocated. 

When defining into a recoverable catalog, FILE also 
identifies the volume containing the base cluster's index 
component (when the base cluster is key sequenced) or data 
component (when the base cluster is entry sequenced). 

When the alternate index is cataloged in a recoverable 
catalog, the DD statement can be concatenated if the g 

volumes are a different device type. Part of the 
concatenated DD statement describes the alternate index’s % 

or component’s volumes (of one device type); the other part 
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of the DD statement describes the volume that contains the 
catalog recovery area (of another device type). 

If the FILE parameter is not specified, an attempt is made 
to dynamically allocate the required volumes. The 
volume(s) must be mounted as permanently resident or 
reserved. 

The DD statement you specify must be in the form* 

//ddname DD UNIT=(devtypeC*unitcount])t 
// VOL=SER=(volserl,volser2,volser3. 

Note: When FILE refers to more than one volume of the same 

device type, the DD statement that describes the volumes 
cannot be a concatenated DD statement. 

FREESPACE ( CIzMCfifilli l ) 

specifies the amount of space that is to be left empty 
after any primary or secondary allocation and any split of 
control intervals (CI~percent) and control areas 
(CA-percent) when the alternate index is built (see 
"BLDINDEX" on page 49). 

The amount of empty space in the control interval and 
control area is available for data records that are updated 
and inserted after the alternate index is initially built. 

The amounts are specified as percentages. 

• CI-percent translates into a number of bytes that is 
equal to, or slightly less than, the percentage value 
of Cl-percent. 

• CA~percent translates into a number of control 
intervals that is equal to, or less than, the 
percentage value of CA-percent. 

The percentages, which must be equal to or less than 
100, can be expressed in decimal (n), hexadecimal 
(X^ 1 ), or binary (B'n 1 ) form. 

When you specify 100X of free space, one data record is 
placed in the first control interval of each control area 
when the alternate index is built. 

Abbreviation: FSPC 

IMBED I MIMES 

specifies whether the sequence set (the lowest level of the 
index) is to be placed with the alternate index f s data 
component. 

IMBED 

specifies that the sequence-set record for each 
control area is to be written as many times as it will 
fit on the first track adjacent to the control area. 

If the allocation is less than a cylinder, one track 
will be added to the primary and secondary allocation 
quantities. 

Abbreviation: IMBD 

NOIMBED 

specifies that the sequence-set record for each 
control area is to be written with the other index 
records. 

Abbreviation: NIMBD 

The IMBED INOIMBED parameter interacts with the 
REPLICATE|NOREPLICATE parameter in determining the physical 
attributes of the index of the alternate index. These 
index attributes can be used in the following combinations: 
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• The sequence-set records are adjacent to the data 
control areas/ and only the sequence-set records are 
replicated (IMBED and NOREPLICATE). 

• The sequence-set records are adjacent to the data 
control intervals/ and all levels of index records are 
replicated (IMBED and REPLICATE). 

• All index records are together/ and all index records 
are replicated (REPLICATE and NOIMBED). 

• All index records are together/ and no index records 
are replicated (NOREPLICATE and NOIMBED). 

For some applications/ specifying index options can improve 
the application f s performance. For information on how the 
index's optional attributes affect performance/ see VSAM 

Adminis±ca^ a . 

KEYRANGES( (IohRsy hJ^hRey) 

E tlflw& B y M,flbis.ey)... 3) 

specifies that portions of the alternate index’s data 
component are to be put on different volumes. Each portion 
of the alternate index is called a key range. 

The maximum number of key ranges for an alternate index is 
123. Key ranges must be in ascending order, and are not 
allowed to overlap. However, a gap can exist between two 
key ranges. You cannot insert records within the gap. 

Keys can contain 1 to 64 characters, 1 to 128 hexadecimal 
characters if coded as X'lowkey* X'highkey*. 

lowijey 

specifies the low key of the key range. If lowkey is 
shorter than the actual keys, it will be padded on the 
right with binary zeros. 


specifies the high key of the key range. If highkey 
is shorter than the actual keys, it will be padded on 
the right with binary ones. 

The KEYRANGES parameter interacts with other DEFINE 
ALTERNATEINDEX parameters. You should ensure that the 
KEYRANGES you specify for the alternate index are 
consistent with the alternate index's other attributes. 

• VOLUMES? There should be as many volume serial numbers 
in the volser list as there are key ranges. 

When a volume serial number is duplicated in the volser 
list, more than one key range is allocated space on the 
volume. When more than one key range is to be 
contained on a volume, UNIQUE cannot be coded for the 
alternate index's data component. 

When there are more volumes in the volser list than 
there are key ranges, the excess volumes are used for 
overflow records from any key range without 
consideration for key range boundaries. 

When there are fewer volumes in the volser list than 
there are key ranges, the excess key ranges are 
allocated on the last volume specified. UNIQUE cannot 
also be specified. 

• UNIQUE? When UNIQUE is specified, each key range 
resides in its own VSAM data space on a separate 
volume. Other key ranges for the alternate index 
cannot also reside on the volume. 

• ORDERED: There is a one-to-one correspondence between 
the volumes in the volser list and the key ranges? The 
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first volume on the volume list contains the first key 
range, the second volume contains the second key range, 
and so on. 

If a volume cannot be allocated in the order specified 
by the volser list, your alternate index definition job 
terminates with an error message. (For example, the 
job would terminate if there were no space on one of 
the volumes specified.) 

• KEYS: The low key and high key values must not exceed 
the key length specified in the KEYS parameter. The 
KEYS parameter must be specified in the same component 
as the KEYRANGE parameter. 

Abbreviation: KRNG 

KEYSCl&ggth gffsellM 0) 

describes the alternate-key field in the base cluster's 
data record. 

The key field of an alternate index is called an alternate 
key. The data record's alternate key can overlap or be 
contained entirely within another (alternate or prime) key 
field. 

The sum of length plus offset cannot be greater than the 
length of the base cluster's data record. 

When the base cluster's data record is allowed to span 
control intervals, the record's alternate-key field is 
within the record’s first segment (that is, in the first 
control interval). 

l en g th offset 

specifies the length of the alternate key (between 1 
and 255), in bytes, and its displacement from the 
beginning of the base cluster’s data record, in bytes. 
You can express length and offset in decimal (n), 
hexadecimal (X'n’), or binary (B’n 1 ) form. 

MASTERPWC password ) 

specifies a master password for the entry being defined. 

The master password allows all access method services 
operations against the alternate index entry and its data 
and index entries, and allows the user's program to access 
the alternate index’s contents without restriction. For 
more details on how passwords can be used, see Catalog 
M m in l s i r ati pd Q m i d a or 

The AUTHORIZATION, CODE, and ATTEMPTS parameters have no 
effect unless the entry has a master password associated 
with it. If MASTERPW is not specified, the highest-level 
password specified becomes the password for all higher 
levels. 

Abbreviation: MRPW 

MOD E L (ry name C /pa s swocd 3 
i catname C/ password 33) 

specifies an existing entry to be used as a model for the 
entry being defined. 

You can use an existing alternate index's entry as a model 
for the attributes of the alternate index being defined. 

For details about how a model is used, see Catalog 

M num s fratL o j},.fiyi d e. 

You may use some attributes of the model and override 
others by explicitly specifying them in the definition of 
the cluster or component. If you do not want to add or 
change any attributes, you need specify only the entry type 
(alternate index, data, or index) of the model to be used 
and the name of the entry to be defined. 
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Unless another entry is specified with the MODEL parameter 
as a subparameter of DATA or INDEX, when you use an 
alternate index entry as a model for an alternate index, 
the data and index components of the model entry are used 
as models for data and index components of the entry still 
to be defined. 

$ X&XXMa M & 

names the entry to be used as a model, 

p a s. s Hp n .d 

specifies a password. If the model entry is 
password-protected and it is cataloged in a 
password-protected catalog, you supply the read- or 
highei—level password of either the model entry or its 
catalog. If you supply both passwords, the catalog's 
password is used. RACF: The read or higher RACF 
authority to the model or catalog is required. 

If you are not specifying new protection attributes 
for the alternate index and you wish to copy the 
model's passwords and protection attributes, you must 
supply the master password of either the model entry 
or its catalog. RACF: The alter RACF authority to the 
model or catalog is required. 

salname 

names the model entry's catalog. You must identify 
the catalog that contains the model entry when: 

• You want to specify the catalog's password instead 
of the model entry's password. 

• The model entry's catalog is not identified with a 
JOBCAT or STEPCAT DD statement, and is not the 
master catalog. 

If the catalog's volume is physically mounted, it is 
dynamically allocated. The volume must be mounted as 
permanently resident or reserved. For information 
about the order in which a catalog is selected when 
the catalog's name is not specified, see "Order of 
Catalog Selection for DEFINE" on page 16. 

ORDERED | UMORMREB 

specifies whether volumes are to be used in the order in 
which they are listed in the VOLUMES parameter. 

ORDERED 

specifies that the volumes are to be used in the order 
in which they are listed for the VOLUMES parameter. 

When you want each key range to reside on a separate 
volume, you can use ORDERED so that the first key 
range goes on the first volume, the second key range 
goes on the second volume, and so on. 

If ORDERED is specified and the volumes cannot be 
allocated in the order specified, the command is 
terminated. (For example, the command would terminate 
if there were no space on one of the volumes 
specified.) 

Abbreviation: ORD 

UNORDERED 

specifies no order for the use of the volumes 
specified in the VOLUMES parameters. 

Abbreviation: UNORD 

OWNERCm ne r i d) 

specifies the identification of the alternate index's 
owner. 
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Note to TSO users: 

If the owner is not identified with the OWNER parameter, 
the TSO user f s userid becomes the ownerid. 

READ PW( password ) 

specifies a read password for the entry being defined. The 
read password permits read operations against the entry's 
records. 

When specified as a parameter of DATA or INDEX, the read 
password allows the user's program to open the data 
component or the index component for read-only processing 
of the component's data records (that is, the data portion 
of the sorted record, not the control fields VSAM inserts 
into stored records). For more details on how passwords 
can be used, see .Ga.tfi.LQg. 

Abbreviation: RDPW 

RECORDSlZECav^raae m>dj0uimIM§6 32MQ .) 

specifies the average and maximum length, in bytes, of an 
alternate index record. 

An alternate index record can span control intervals, so 
RECORDSIZE can be larger than CONTROLINTERVALSIZE. average 
and maximum are any integer values that do not exceed the 
capacity of a control area. It can be expressed in decimal 
(n), hexadecimal (X'n 1 ), or binary (B'n*) form. You can 
identify the records as fixed length by specifying the same 
value for average and maximum. 

You can use the following formulas to determine the size of 
the alternate index record when the alternate index 
supports: 

• A key sequenced base cluster 

RECSZ = 5 + AIXKL + (n x BCKL) 

• An entry sequenced base cluster 

RECSZ = 5 + AIXKL + (n x 4) 


where: 

— RECSZ is the average record size. 

- AIXKL is the alternate-key length (see the KEYS 
parameter). 

— BCKL is the base cluster's prime-key length (you 
can issue the access method services LISTCAT 
command to determine the base cluster's prime-key 
length). 

n = 1 when UNIQUEKEY is specified (RECSZ is also 
the maximum record size). 

— n = the number of data records in the base cluster 
that contain the same alternate-key value, when 
NONUNIQUEKEY is specified. 

When you also specify NONUNIQUEKEY, the record size you 
specify should be large enough to allow for as many key 
pointers or RBA pointers as you anticipate. The record 
length values apply only to the alternate index's data 
component. 

Note: REPRO and EXPORT will not support data sets with 

record sizes greater than 32760. 

Abbreviation: RECSZ 
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REPLICATE 1 NOREPLICATE 

specifies how many times each record in the alternate 
index's index component is to be written on a direct access 
device track. 

For a discussion of the relationship between IMBED)N01MBED 
and REPLICATE)NQREPLICATE, see the IMBEDlNOIMBED parameter 
above. 

REPLICATE 

specifies that each index record is to be written on a 
DASD track as many times as it will fit. 

When you specify REPLICATE, rotational delay is 
reduced and performance is improved. However, the 
alternate index's index usually takes more direct 
access device space. 

Abbreviation: REPL 

NOREPLICATE 

specifies that the index record is to be written on a 
DASD track only one time. 

Abbreviation: NREPL 

REUSE IHQREHSE 

specifies whether the alternate index can be used over and 
over as a new alternate index. 

REUSE 

specifies that the alternate index can be used over 
again as a new alternate index. When a reusable 
alternate index is opened, its high-used RBA can be 
set to zero if you open it with an access control 
block that specifies the RESET attribute. 

When you use BLDINDEX to build a reusable alternate 
index, the high-used RBA is always reset to zero when 
the alternate index is opened for BLDINDEX processing. 

You cannot specify REUSE when you also specify 
KEYRANGES or UNIQUE for the alternate index or its 
components. Reusable alternate indexes may be 
multivolumed and are restricted to 16 physical extents 
per volume. 

Abbreviation: RUS 

NOREUSE 

specifies that the alternate index cannot be used 
again as a new alternate index. 

Abbreviation: NRUS 

SHAREOPTIONSC SLQSSL3J3ism C II 3) 

specifies how an alternate index's data or index component 
can be shared among users. 

For data integrity purposes, you should make sure that 
share options specified for data and index components are 
the same. For a full description of data set sharing, see 

]£5A 1 1.,A^ ri jss * 

specifies the amount of sharing allowed among regions 
within the same system or within multiple systems 
using global resource serialization (GRS). 

Independent job steps in an operating system or 
multiple systems using GRS can access a VSAM data set 
concurrently. To share a data set, each user must 
specify DISP=SHR in the data set's DD statement. The 
values that can be specified are: 
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1 

specifies that the data set can be shared by any 
number of users for read processing, or the data 
set can be accessed by only one user for read and 
write processing. With this option, VSAM ensures 
complete data integrity for the data set. 

2 

specifies that the data set can be accessed by 
any number of users for read processing and it 
can also be accessed by one user for write 
processing. With this option, VSAM ensures write 
integrity by obtaining exclusive control for a 
control interval when it is to be updated. 

If a user requires read integrity, it is that 
user's responsibility to use the ENQ and DEQ 
macros appropriately to provide read integrity 
for the data the program obtains. (For 
information on using ENQ and DEQ, see System 

3 

specifies that the data set can be fully shared 
by any number of users. With this option, each 
user is responsible for maintaining both read and 
write integrity for the data the program 
accesses. 

User programs that ignore the write integrity 
guidelines can cause VSAM program checks, lost or 
inaccessible records, uncorrectable data set 
failures, and other unpredictable results. This 
option places heavy responsibility on each user 
sharing the data set. 

4 

specifies that the data set can be fully shared 
by any number of users, and buffers used for 
direct processing are refreshed for each request. 
This option requires your program to use the ENQ 
and DEQ macros to maintain data integrity while 
sharing the data set. Improper use of the ENQ 
macro can cause problems similar to those 
described under SHAREOPTIONS 3. (For information 
on using ENQ and DEQ, see SygJLQ.Pl 
JEaciJJJtlos. ) 

specifies the amount of sharing allowed among systems. 
Job steps of two or more operating systems can gain 
access to the same VSAM data set regardless of the 
disposition specified in each step's DD statement for 
the data set. 

To get exclusive control of the data set's volume, a 
task in one system issues the RESERVE macro. The 
level of cross-system sharing allowed by VSAM applies 
only in a multiple operating system environment. The 
values that can be specified are: 

1 

Reserved 

2 

Reserved 

3 

specifies that the data set can be fully shared. 
With this option, each user is responsible for 
maintaining both read and write integrity for the 
data that user's program accesses. User programs 
that ignore write integrity guidelines can cause 
VSAM program checks, uncorrectable data set 
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failures, and other unpredictable results. This 
option places heavy responsibility on each user 
sharing the data set. 


4 

specifies that the data set can be fully shared. 
Buffers used for direct processing are refreshed 
for each request. 

This option requires that you use the RESERVE and 
DEQ macros to maintain data integrity while 
sharing the data set. (For information on using 
RESERVE and DEQ, see System Macros and 
Facilities .) Writing is limited to PUT-update 
and PUT-insert processing that does not change 
the high-used RBA if your program opens the data 
set with DISP=SHR. 

Data set integrity cannot be maintained unless 
all jobs accessing the data set in a cross-system 
environment specify DISP=SHR. Improper use of 
the RESERVE macro can cause problems similar to 
those described under SHAREOPTIONS 3. 

To ensure data integrity in a shared environment, VSAM 
provides users of SHAREOPTIONS 4 (cross-region and 
cross-system) with the following assistances 

• Each PUT request results in the appropriate buffer 
being written immediately into the VSAM object’s direct 
access device space. VSAM writes out the buffer in the 
user’s address space that contains the new or updated 
data record. 

• Each GET request results in all the user’s input 
buffers being refreshed. The contents of each data and 
index buffer being used by the user’s program are 
retrieved from the VSAM object’s direct access device. 

Abbreviation: SHR 

SPEED IRECMERY 

specifies whether the data component’s control areas are to 
be preformatted before alternate index records are loaded 
into them. 

When you specify RECOVERY, your initial load takes longer 
because the control areas are written initially with 
end-of-file indicators and again with your alternate index 
records. When you specify SPEED, your initial load is 
quicker. 

SPEED 

specifies that the data component’s space is not to be 
preformatted. Its space might contain data records 
from a previous use of the space, or it might contain 
binary zeros; its contents are unpredictable. 

If the initial load fails, you must load the alternate 
index records again from the beginning because VSAM is 
unable to determine where your last correctly written 
record is. VSAM cannot find a valid end-of-file 
indicator when it searches your alternate index 
records. 

RECOVERY 

specifies that the data component’s control areas are 
written with records that indicate end-of-file. When 
an alternate index record is written into a control 
interval, it is always followed by a record that 
identifies the record that has just been written as 
the last record in the alternate index. 
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If the initial load fails, you can resume loading 
alternate index records after the last correctly 
written record, because an end-of-file indicator 
identifies it as the last record. 

Abbreviation: RCVY 

STAGE |BIND ICYLINDERFAULT 

specifies how an alternate index or component that is 
stored on a mass storage volume is to be staged. 

When the alternate index or component is not stored on a 
mass storage volume, the attribute is ineffective until the 
direct access storage volume on which the alternate index 
or component is stored is converted to a mass storage 
volume. (The CONVERTV command used for this conversion is 
described in to r 33 e £ysElfitfl & gC-Q 

In f -Q r . m . a . t ip.o •) 

Unless the sequence set of the index component is embedded 
in the data, when one of these parameters is specified for 
the data component and another parameter is specified for 
the index component, the components are staged separately 
as specified. In that case, the parameter specified for 
the index component applies to both components. 

STAGE 

indicates that the alternate index or component is to 
be staged from mass storage to a direct access storage 
staging drive when the alternate index or component is 
opened. 

If the alternate index or component cannot be staged 
at open time because of heavy staging activity of 
other objects, data is staged as the processing 
program needs it. 


BIND 

indicates that the alternate index or component is not 
only to be staged, but also to be bound—that is, 
retained on the direct access storage staging drive 
until it is closed. If the alternate index or 
component cannot be staged at open time because of 
heavy staging activity of other objects, data is 
staged as the processing program needs it. 

CYLINDERFAULT 

indicates that the alternate index or component is not 
to be staged when it is opened, but that data from it 
is to be staged as the processing program needs it. 

Abbreviation: CYL F 

TO(daj^)lFORCday§) 

specifies the retention period for the alternate index. 

The alternate index is not automatically deleted when the 
expiration date is reached. When you do not specify a 
retention period, the alternate index can be deleted at any 
time. 

TQ(datg) 

specifies the date, in the form yyddd, where yy is the 
year and ddd is the Julian date (001, for January 1, 
through 365, for December 31), through which the 
alternate index is to be kept before it is allowed to 
be deleted. 

FOR(days) 

specifies the number of days for which the alternate 
index is to be kept before it is allowed to be 
deleted. days can be expressed in decimal (n), 
hexadecimal (X’n 1 ), or binary (B , n l ) form. 
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The maximum number that can be specified for days is 
9999. If the number specified is 0 through 1830/ the 
retention period is the number of days specified. If 
the number specified is between 1831 and 9999/ the 
retention period is through the year 1999. 

UNIQUE iSUMUJmmON 

specifies whether the alternate index f s components are 
allocated an amount of space from the volume f s available 
space (UNIQUE) or from a VSAM data space's available space 
(SUBALLOCATION) . 

UNIQUE 

specifies that a VSAM data space is to be built and 
assigned exclusively to each component of the 
alternate index. The data space is created when the 
alternate index is defined. The alternate index f s 
volume(s) must be mounted. 

VSAM builds a DSCB in the volume f s table of contents 
(VTOC) to describe the data space. The name of the 
data space/ which is the same as the components name/ 
is put in the DSCB. A subentry is added to the volume 
entry (in the VSAM catalog) to describe the VSAM data 
space. 

Abbreviation: UNQ 
SUBALLOCATION 

specifies that space from one of the VSAM data spaces 
on the volume is to be assigned to the alternate 
index's component. 

Abbreviation: SUBAL 

The space allocation attribute interacts with other DEFINE 
ALTERNATEINDEX parameters. You should ensure that the 
space allocation attribute you specify for the alternate 
index is consistent with other attributes: 

• REUSE: You cannot specify REUSE when you specify UNIQUE 
for an alternate index or its components. 

• KEYRANGES: When UNIQUE is specified/ a data space is 
built and allocated on a separate volume for each key 
range. 

• VOLUMES: When UNIQUE is not specified/ VSAM data space 
must exist on the volume that is to contain the 
alternate index's component. 

When UNIQUE is specified/ and more than one volume is 
specified, VSAM must already own all the volumes except 
the first. If there is no VSAM space on a volume, you 
must execute a DEFINE SPACE CANDIDATE before your 
DEFINE UNIQUE. 

UNIQUEKEY1 mmm& m& l 

specifies whether more than one data record (in the base 
cluster) can contain the same key value for the alternate 
index. 

UNIQUEKEY 

specifies that each alternate index key points to only 
one data record. When the alternate index is built 
(see "BLDINDEX*' on page 49) and more than one data 
record contains the same key value for the alternate 
index, the BLDINDEX processing terminates with an 
error message. 

Abbreviation: UNQK U 

V.y 
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NONUNIQUEKEY 

specifies that a key value for the alternate index can 
point to more than one data record in the base 
cluster. The alternate index's key record can point 
to a maximum of 32768 records with nonunique keys. 

When you specify NONUNIQUEKEY/ the value you specify 
as the maximum record size should be large enough to 
allow for alternate index records that point to more 
than one data record. 

Abbreviations: NUNQK 

UPDATEPWC password ) 

specifies the update password for the entry being defined. 
The update password permits read and write operations 
against the entry's records. 

When specified as a parameter of DATA or INDEX/ the update 
password allows the user's program to open the data 
component or index component for read and write processing 
of the component's VSAM records (that is, the data portion 
of the stored record/ not the control fields that VSAM 
inserts into stored records). 

If a read password is the only password specified for the 
object (that is, it is the highest-level password)/ it 
propagates upward and becomes the password for all higher 
levels. If you specify a highei—level password and do not 
specify an update password/ the update or read password is 
null. 

Abbreviation: UPDPW 
ULOBADEI NOUPGRADE 

specifies whether the alternate index is to be upgraded 
(that is, kept up to date) when its base cluster is 
modified. 

UPGRADE 

specifies that the cluster's alternate index is 
upgraded to reflect changed data when the base 
cluster's records are added to/ updated/ or erased. 

When UPGRADE is specified/ the alternate index's name 
is cataloged with the names of other alternate indexes 
for the base cluster. The group of alternate index 
names identifies the upgrade set that includes all the 
base cluster's alternate indexes that are opened when 
the base cluster is opened for write operations. 

The UPGRADE attribute is not effective for the 
alternate index until the alternate index is built 
(see "BLDINDEX" on page 49). If the alternate index 
is defined when the base cluster is open, the UPGRADE 
attribute takes effect the next time the base cluster 
is opened. 

Abbreviation: UPG 

NOUPGRADE 

specifies that the alternate index is not to be 
upgraded when its base cluster is modified. 

Abbreviation: NUPG 
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WRITECHECK I tLQMBIIECMifflK 

specifies whether an alternate index or component is to be , 
checked by a machine action called write check when a r 

record is written into it. V / 

WRITECHECK 

specifies that a record is written and then read/ 
without data transfer/ to test for the data check 
condition. 

Abbreviation: WCK 

NOWRITECHECK 

specifies that the alternate index or component is not 
to be checked by a write check. 

Abbreviation: NWCK 


DATA AND INDEX COMPONENTS OF AN ALTERNATE INDEX 

Attributes can be specified separately for the alternate index's 
data and index components. A list of the DATA and INDEX 
parameters is provided at the beginning of this section. These 
parameters are described in detail as parameters of the 
alternate index as a whole. Restrictions are noted with each 
parameter's description. 


/f 
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DEFINE ALTERNATEINDEX EXAMPLE 


Define an Alternate Index: Example 1 

In this example^ an alternate index is defined. An example for 
DEFINE CLUSTER illustrates the definition of the alternate 
index’s base cluster/ EXAMPLE.KSDS2. A subsequent example 
illustrates the definition of a path/ EXAMPLE.PATH/ that allows 
you to process the base cluster’s data records using the 
alternate key to locate them. The alternate index/ path/ and 
base cluster are defined in the same catalog/ USERRCAT. 

//DEFAIX1 JOB 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT=A 

//SYSIN DD X 

DEFINE ALTERNATEINDEX - 

(NAMECEXAMPLE.AIX) - 
RELATE(EXAMPLE.KSDS2) - 
MASTERPWCAIXMRPW) - 
UPDATEPWCAIXUPPW) - 
KEYSC3 0) - 
RECORDSIZEC40 50) - 
VOLUMESCVSERQ1) - 
CYLINDERSC3 1) - 
NONUNIQUEKEY - 
UPGRADE) - 

CATALOG(USERRCAT/USERUPPW) 

/x 

The DEFINE ALTERNATEINDEX command creates an alternate index 
entry, a data entry, and an index entry to define the alternate 
index EXAMPLE.AIX. The DEFINE ALTERNATEINDEX command also 
obtains space for the alternate index from one of the VSAM data 
spaces on volume VSERG4, and allocates 3 cylinders for the 
alternate index’s use. Because the alternate index is being 
defined into a recoverable catalog, the catalog recovery volume 
will be dynamically allocated. The command’s parameters are: 

• NAME, which specifies that the alternate index’s name is 
EXAMPLE.AIX. 

• RELATE, which identifies the alternate index’s base cluster, 
EXAMPLE.KSDS2. 

• MASTERPW and UPDATEPW, which specifies the alternate index’s 
master password, AIXMRPW, and update password, AIXUPPW. 

• KEYS, which specifies the length and location of the 
alternate key field in each of the base cluster’s data 
records. The alternate key field is the first three bytes 
of each data record. 

• RECORDSIZE, which specifies that the alternate index’s 
records are variable-length, with an average size of 40 
bytes and a maximum size of 50 bytes. 

• VOLUMES, which specifies that the alternate index is to 
reside on volume VSER01. This example assumes that the 
volume is already cataloged in the user catalog, USERRCAT. 

• CYLINDERS, which specifies that 3 cylinders are allocated 
for the alternate index’s space. When the alternate index 
is extended, it is to be extended in increments of 1 
cylinder. 

• NONUNIQUEKEY, which specifies that the alternate key value 
might be the same for two or more data records in the base 
cluster. 
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• UPGRADE# which specifies that the alternate index is to be 
opened by VSAM and upgraded each time the base cluster is 
opened for processing. 

• CATALOG# which specifies that the alternate index is to be 
defined in the user catalog# USERRCAT. The example also 
supplies the master catalog's update password# USERUPPN. 
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DEFINE CLUSTER 


The DEFINE CLUSTER command defines a cluster for a 
key-sequenced, entry-sequenced, or relative record data set. 
When you use this command, you can specify attributes for the 
cluster as a whole and for the components of the cluster. The 
general format of the DEFINE CLUSTER command is: 

DEFINE CLUSTER (parameters) - 
(DATA(parameters)3 - 
CINDEX(parameters)3 - 
ECATALOG(subparameters)3 


DEFINE 


CLUSTER 

(NAME (snlc y nam s 3 

ICYLINDERS( primary ! secondary ])I 
RECORDS( primary ! secondary ]31 
TRACKS( primary ! secondary)1} 
VOLUMES(y.ol s .er.I Y. Q .1.5.s r .» « ♦ 1 3 
( ATTEMPTS! niimfa&t: 123] 

(AUTHORIZATION entrypoint ! string ]3] 
(BUFFERSPACE( size )] 

ICODE( code )1 

ICONTROLINTERVALSIZE( size 3] 
!CONTROLPW( password )] 

(DESTAGEWAITl N0DESTAGEWAIT 3 
IERASE I NOERASE ] 
IEXCEPTI0NEXIT( entrypoint 3] 

IFILE( dname )I 
! FREESPACE (.ClrRft Cfifl Di 
! CA-percent 3I 0 531 
(IMBEDI N0IMBED 1 
[ INDEXED !NONINDEXED|NUMBERED] 

!KEYRANGES(( lowkev highkev ) 

!( lowkey highkev )...3)1 

(KEYS(.Le ng t h o ffs e tIM 0 3] 

!MASTERPW( password )1 
! MODE L (eptryng m e. I / pa .S5.W.P. r..d 3 
! catname !/ password ]]31 
(ORDERED I UNORDERED l 
(OWNER! ownend ) 3 
(READPW( password 3] 

(RECORDSIZE(a verase maximum 31 
(REPLICATE I N0REPLICATE 3 
(REUSEIH0RIUSI3 

(SHAREOPTIONS! crossregion 
( crosssvstem ]11 333 
(SPANNED| MONSPANNED ] 

(SPEED I RECOVERY ] 

( STAGE |BIND|CYLINDERFAULT3 
(TO( date )I FOR! days )1 
[UNIQUE I SUBALLOCATION 1 
(UPDATEPW( password )1 
(WRITECHECK | MP.HRlIE.ChE.CK13 


(Continued on next page.) 
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[DATA 

([ATTEMPTS[ number )3 

[AUTHORIZATION (en±cYEain±[ sicimain 
[BUFFERSPACE( size )] 

[CODEC code )] 

[CQNTROLINTERVALSIZEC size )3 
[CONTRO LPW( password )3 
[CYLINDERS[ primary ! secondary !31 
RECORDS! primary ! secondary !)I 
TRACKS(Rcimany[ s&oandacy))) 
[DESTAGEWAZT|N0DESTAGEWAIT3 
[ERASE I NOERASE3 
[EXCEPTIONEXITl entrypoint 3 3 
[FILE! dname )3 

[FREESPACE! Cl-percent ! CA-percent !33 
[KEYRANGES!f lowkev hiohkev ) 

[[ lowkev hiahkev ).♦ ♦ 3) 3 
! KEYS [ length o f f se t)! 

[MASTERPW( password )3 
[MODEL[ entrvname !/ password 3 
[ catname !/ password 3)3 
!NAME[ entryname )3 
[ORDERED|UNORDERED 3 
[QWNER[ ownerid )3 
!READPW! password )3 
[RECORDSIZEC average maximum ) 

[REUSE|NOREUSE3 

[SHAREOPTIONS[ crossregion ! crosssystem !)3 
E SPANNED|NONSPANNED 3 
[SPEED|RECOVERY! 

[STAGEIBINDICYLINDERFAULT3 
[UNIQUE I SUBALLOCATION! 

[UPDATEPW! password )3 
!VOLUMES[ volser [ volser .. ♦ 3)3 
EWRITECHECK|N0WRITECHECK3)3 


[INDEX 

[[ATTEMPTS[ number )3 

[AUTHORIZATION! entrvpoint ! string !)3 
[CODE! code )3 

[CONTROLINTERVALSIZE! size )3 
[CONTROLPWC password )3 
[CYLINDERS[ primary ! secondary !)I 
RECORDS(ErianaryE secondar y)) I 

tracks [ pr im ar y! s -g spn eJa r y))) 

[DESTAGEWAITINODESTAGEWAIT3 
[EXCEPTIONEXIT! entrvpoint ) 3 
EFILEE dname )3 
[IMBED IN0IMBED3 
[MASTERPW! password )3 
[MODEL[ entrvname [/ password 3 
[ . ca t na ia e [ / pas sw o rd 3 3)) 

[NAME! entrvname 33 
[ORDERED|UNORDERED3 
[OWNER! ownerid )3 
[READPW! passwo rd)3 
[REPLICATE IN0REPLICATE3 
[REUSE|NOREUSE3 

[SHAREOPTIONS!e rpssrg gj p n! crosssystem !)3 
[STAGE|BIND|CYLINDERFAULT 3 
[UNIQUE I SUBALLOCATION! 

[UPDATEPW( password )3 
[VOLUMES[ volser ! volser ...3)3 
[WRITECHECK|N0WRITECHECK3)3 

[CATALOG! catname [/ password ))3 


DEFINE can be abbreviated: DEF 
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DEFINE CLUSTER PARAMETERS 


Required Parameters 


CLUSTER 

specifies that a cluster is to be defined. 

The CLUSTER keyword is followed by the parameters specified 
for the cluster as a whole. These parameters are enclosed 
in parentheses and, optionally, are followed by parameters 
specified separately for the DATA and INDEX components. 

Abbreviation: CL 

NAME [ gntoimms) 

specifies the cluster's entryname or the name of each of 
its components. The entryname specified for the cluster as 
a whole is not propagated to the cluster f s components. 

You can define a separate entryname for the cluster, its 
data component, and its index component. If no name is 
specified for the data and index component, a name is 
generated. When the cluster, data component, and index 
component are individually named, each can be addressed. 

CYLINDERS! primary ! secondary ])I 

records t B r im r y ! saaandar y]) I 

TRACKS( primary ! secondary ]) 

specifies the amount of space to be allocated to the 
cluster from the volume's available space, when UNIQUE is 
specified, or from the available space of one of the 
volume's VSAM data spaces. 

If you do not specify the MODEL parameters, you must 
specify one, and only one, of the following parameters: 
CYLINDERS, RECORDS, or TRACKS. 

When you specify UNIQUE, space is always allocated in 
cylinders. If the amount of space you specify for the data 
component of the cluster is not an even multiple of 
cylinder size, VSAM rounds the allocation upward to a 
multiple of a cylinder. 

If you specify RECORDS, the amount of space allocated is 
the minimum number of tracks that are required to contain 
the specified number of records. 

Regardless of the allocation type, the control area (CA) 
size for the data set is calculated based on the smaller of 
the two allocation quantities (primary or secondary) 
specified in the define command. A CA is never greater than 
a single cylinder, but may be less (that is, some number of 
tracks) depending upon the allocation amount and type used. 
When tracks or records are specified, the space allocation 
unit (the CA size) may be adjusted to one cylinder. This 
occurs if the calculated CA size contains more tracks than 
exist in a single cylinder of the device being used. 

DEFINE RECORDS will allocate sufficient space to contain 
the specified number of records, but variable factors 
unknown at define time (such as key compression or method 
of loading records) may result in inefficient use of the 
space allocated. This may prevent every data CA from being 
completely used, and you may be unable to load the 
specified number of records without requiring secondary 
allocation. 

When UNIQUE or REUSE is specified, each volume can contain 
a maximum of 16 extents. 

When the data component is not divided into key ranges and 
more than one volume is specified, the primary amount of 
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space is allocated only on the first volume when the 
component is defined. The secondary amount must be coded 
to extend the component to additional volumes. When the 
component increases in size so as to extend to additional 
volumes, the first allocation on each overflow volume is 
the primary amount. 

When KEYRANGES is specified and the data component is to be 
contained on more than one volume, the primary amount of 
space is immediately allocated on each volume required for 
the key ranges. If more than one key range is allocated on 
a single volume, the primary amount is allocated for each 
key range. 

Secondary amounts can be allocated on all volumes available 
to contain parts of the cluster regardless of the key 
ranges. 

You can specify the amount of space as a parameter of 
CLUSTER, as a parameter of DATA, or as a parameter of both 
DATA and INDEX. When a key-sequenced cluster is being 
defined and the space is specified as a parameter of: 

• CLUSTER, the amount specified is divided between the 
data and index components. The division algorithm is a 
function of control interval size, record size, device 
type, and other data set attributes. 

If the division results in an allocation for the data 
component that is not an integral multiple of the 
required control area size, the data component's 
allocation is rounded up to the next higher control 
area multiple. This rounding may result in a larger 
total allocation for your cluster than you specified. 

• DATA, the entire amount specified is allocated to the 
data component. An additional amount of space, 
depending on control interval size, record size, device 
type, and other data set attributes, is allocated to 
the index component. 

To determine the exact amount of space allocated to each 
component, list the clusters catalog entry, using the 
LISTCAT command. 

When you specify UNIQUE, and the cluster's data space is 
the first data space on a volume that belongs to a 
recoverable catalog, the equivalent in tracks of one 
additional cylinder is allocated for the recovery area data 
space. 

The primary and each secondary allocation must be able to 
be satisfied in 5 extents; otherwise, your DEFINE or data 
set extension will fail. 

J BO J B3TY 

specifies the initial amount of space that is to be 
allocated to the cluster. 

asc flfldary 

specifies the amount of space that is to be allocated 
each time the cluster extends, as a secondary extent. 
When secondary is specified and the cluster is 
suballocated, space for the cluster's data and index 
components can be expanded to include a maximum of 123 
extents. 

If the data space that contains all or part of the 
cluster cannot be extended because the cluster's 
secondary allocation amount is greater than the data 
space's secondary allocation amount, VSAM builds a new 
data space. The new data space's primary and 
secondary allocation amounts are equal to the 
cluster's secondary allocation amount. 
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primary and secondary can be expressed in decimal (n), 
hexadecimal CX'n'), or binary (B'n') form. 

Abbreviations: CYL, REC, and TRK 

VOLUMES(yj B jj s &r.E yjalsgr*.. 3) 

specifies the volume(s) on which a cluster’s components are 
to have space. 

If you do not specify the MODEL parameter, VOLUMES must be 
specified either as a parameter of CLUSTER, or as a 
parameter of both DATA and INDEX. 

If the data and index components are to reside on different 
device types, you must specify VOLUMES as a parameter of 
both DATA and INDEX. 

If more than one volume is listed with a single VOLUMES 
parameter, the volumes must be of the same device type. 

The volume serial number may be repeated in the list only 
if the KEYRANGE parameter is specified. You may want to do 
this in order to have more than one key range on the same 
volume. Even in this case, repetition is only valid if all 
duplicate occurrences are used for the primary allocation 
of some key range. 

In a system with the Mass Storage System, a cluster or 
component can be defined on a mass storage volume. 

The VOLUMES parameter interacts with other DEFINE CLUSTER 
parameters. You should ensure that the volume(s) you 
specify for the cluster is consistent with the cluster's 
other attributes: 

• SUBALLOCATION: If UNIQUE is not specified, the volume 
must already contain VSAM data space. 

• KEYRANGES: If KEYRANGES and UNIQUE are specified, a 
VSAM data space is built and allocated on a separate 
volume for each key range. 

• ORDERED: If ORDERED is specified, the volumes are used 
in the order listed. If ORDERED and KEYRANGES are 
specified, there is a one-to-one correspondence between 
the key ranges in the key range list and the volumes in 
the volser list. 

• CYLINDERS, RECORDS, TRACKS: The volumeCs) must contain 
enough unallocated space to satisfy the component's 
primary space requirement. 

• FILE: The volume information supplied with the DD 
statement(s) pointed to by FILE must be consistent with 
the information specified for the cluster and its 
components. 

• CATALOG: The data space on the volume must be defined 
before the cluster, and the catalog specified must own 
the volume. 

Abbreviation: VOL 
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ATTEMPTS C gumfa&E 12 3 

specifies the maximum number of times the operator can try 
to enter a correct password in response to a prompting 
message. This parameter only has effect when the entry’s 
master password is not null. A prompting message is issued 
only when the user has not already supplied the appropriate 
password. 

number 

can be any number, 0 through 7. If 0 is specified, 
the operator is not prompted and is not allowed to 
enter a password from the console. number can be 
expressed in decimal (n), hexadecimal CX’n’), or 
binary (B’n*) form. 

Note to TSO Users: At a TSO terminal, the logon 
password is checked first, before the user is prompted 
to supply a password for the cluster. Checking the 
logon password counts as one attempt to obtain a 
password. If ATTEMPTS is not specified, the user has 
one attempt to supply the cluster’s password, because 
the default is 2. 

Abbreviation: ATT 

AUTHORIZATION!fr nixypo antt siding!) 

specifies that a usei—security-verification routine (USVR) 
is available for additional security verification. Hhen a 
protected cluster is accessed and the user supplies a 
correct password other than the cluster’s master password, 
the USVR receives control. For details on the USVR, see 
. 

If a USVR is loaded from an unauthorized library during 
access method services processing, an abnormal termination 
will occur. 

This parameter only has effect when the entry’s master 
password is not null. 


specifies the name of the user’s-security-verification 
routine. 

di c i n g 

specifies information to be passed on to the USVR when 
it receives control to verify authorization. 

Abbreviation: AUTH 

BUFFERSPACEt size ) 

specifies the minimum space to be provided for buffers. 

The buffer space size you specify helps VSAM determine the 
data component’s and index component’s control interval 
size. If BUFFERSPACE is not coded, VSAM attempts to get 
enough space to contain two data component control 
intervals and, if the data is key sequenced, one index 
component control interval. 

SJUSfi 

is the amount of space to be provided for buffers. 

Size can be expressed in decimal Cn), hexadecimal 
CX’n’), or binary (B’n*) form, but must not exceed 
16776704. 
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The size specified cannot be less than enough space to 
contain two data component control intervals and/ if 
the data is key sequenced/ one index control interval. 
If the specified size is less than VSAM requires for 
the buffers needed to run your job/ VSAM terminates 
your DEFINE and provides an appropriate error message. 

Abbreviations: BUFSP or BUFSPC 

CATALOG C satn a mg C /* ?3 .ss wp x..d 3) 

identifies the catalog in which the cluster is to be 
defined. For information about the order in which catalogs 
are selected/ see "Order of Catalog Selection for DEFINE” 
on page 16. 

£3.1aaillg 

specifies the name of the catalog in which the entry 
is to be defined. 

EassMacd 

specifies the catalog's password. If the catalog is 
password protected/ you must supply the update- or 
highei—level password. If no password is specified/ 
VSAM will prompt the operator for the correct 
password. RACF: The update or higher RACF authority 
to the catalog is required. 

If the catalog's volume is physically mounted/ it is 
dynamically allocated. The volume must be mounted as 
permanently resident or reserved. 

Abbreviation: CAT 

CODEC^gdg) 

specifies a code name for the entry being defined. If an 
attempt is made to access a password protected entry 
without a password/ the code name is used in a prompting 
message. The code enables the operator to be prompted for 
the password without disclosing the name of the entry. 

If CODE is not specified and an attempt is made to access a 
cluster or component that is password protected without 
supplying a password/ the operator will be prompted with 
the name of the entry. 

This parameter only has effect when the cluster's or 
component's master password is not null. 

CONTROLINTERVALSIZEt size ) 

specifies the size of the control interval for the cluster 
or component. 

If CONTROLINTERVALSIZE is specified on the cluster level/ 
it propagates to the component level at which no 
CONTROLINTERVALSIZE has been specified. 

The size of the control interval depends on the maximum 
size of the data records and the amount of buffer space you 
provide. If the size you specify is not an integer 
multiple of 512 or 2048/ VSAM selects the next higher 
multiple for your cluster's control interval size. 

If CONTROLINTERVALSIZE is not coded, VSAM determines the 
size of control intervals. If you have not specified 
BUFFERSPACE and the size of your records permits, VSAM uses 
the optimum size for the data component and 512 for the 
index component. 

size 

for a cluster's data component. 

If SPANNED is not specified, the size of a data 
control interval must be at least 7 bytes larger than 
the maximum record length. 
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If the control interval specified is less than maximum 
record length plus a 7-byte overhead, then VSAM will 
increase the data control interval size to contain the 
maximum record length plus the needed overhead. 

If SPANNED is specified, the control interval size can 
be less than the maximum record length. The sizes you 
can specify (between 512 and 32768 bytes) are an 
integer multiple of 512 or 2048: 

CISZ = (n x 512) or (n x 2048) 
where n is a positive integer from 1 to 16. 


S±Z& 

for a key-sequenced cluster f s index component. 

You can specify the following values: 

CISZ = E512 | 1024 | 2048 I 40961 

When you specify a size that is not a multiple of 512 or 
2048, VSAM chooses the next higher multiple. 

For a discussion of the relationship between control 
interval size and physical block size, refer to Optimizing 
VSAM Performance” in VSAM Administration Guide . The 
discussion also includes restrictions that apply to control 
interval size and physical block size. 

Abbreviations: CISZ or CNVSZ 

CONTROLPW(ESSSHgrd) 

specifies a control password for the entry being defined. 

When specified as a parameter of DATA or INDEX, the control 
password allows the user*s program to open the data 
component or index component for read and write processing 
of the component’s control intervals (that is, the entire 
control interval, including the data portion of stored 
records and the control fields VSAM inserts into stored 
records and control intervals). 

If a read or update password is the only password specified 
for the object, it (the highest-level password) propagates 
upward and becomes the password for all higher unspecified 
levels. 

Abbreviation: CTLPW 
DESTAGEWAIT1 UQMSIAMMM1 

specifies whether a cluster or its component that is stored 
on a mass storage volume is to be destaged synchronously or 
asynchronously with respect to the program that closes it. 

Note: When the cluster or component is not stored on a 

mass storage volume, the attribute is ineffective until the 
direct access storage volume the cluster or component is 
stored on is converted to a mass storage volume by way of 
the C0NVERTV command. (CONVERTV is described in OS/VS Mass 
Storage System (MSS) Services: Reference Information .) 

DESTAGEWAIT 

indicates that destaging is to be completed before 
VSAM returns control to the program that issued the 
CLOSE macro. VSAM can thus notify the program whether 
destaging was successful. 

Abbreviation: DSTGW 
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NODESTAGEWAXT 

indicates that notification of unsuccessful destaging 
is to be made only by a message to the operator. 

Abbreviation: NDSTGW 

When one of these parameters is specified for the data 
component and the other parameter is specified for the 
index component, the components are destaged separately as 
specified, unless the sequence set of the index component 
is embedded in the data. In that case, the parameter 
specified for the index component applies to both 
components. 

ERASE 1 MflEBASE 

specifies whether the clusters data component is to be 
erased when its entry in the catalog is deleted. 

ERASE 

specifies that the data component is to be overwritten 
with binary zeros when its catalog entry is deleted. 

Abbreviation: ERAS 

NOERASE 

specifies that the data component is not to be 
overwritten with binary zeros. 

Abbreviation: NERAS 

EXCEPTI ONEX IT l sn.tr.YJ?.siD±) 

specifies the name of a usei—written routine, called the 
exception exit routine, that receives control when an 
exceptional I/O error condition occurs during the transfer 
of data between your program f s address space and the 
cluster’s direct access storage space. 

An exception is any I/O error condition that causes a SYNAD 
exit to be taken. The component’s exception-exit routine 
is processed first, then the user’s SYNAD-exit routine 
receives control. 

If an exception exit routine is loaded from an unauthorized 
library during access method services processing, an 
abnormal termination will occur. See r . at i.Q n 

Guide. 

Abbreviation: EEXT 
FlLECdoaom) 

names the DD statement that identifies the direct access 
device(s) and volume(s) on which space is to be allocated 
to the cluster. If more than one volume is specified, all 
volumes must be the same device type. 

If data and index components are to reside on separate 
devices, you can specify a separate FILE parameter as a 
parameter of DATA and INDEX to point to different DD 
statements. 

When the cluster is defined in a recoverable catalog, and 
FILE is specified as a parameter of CLUSTER, the FILE 
parameter can identify the DD statement for all volumes on 
which space is to be allocated* The DD statement can be 
concatenated if the volumes are of different device types: 
Part of the concatenated DD statement describes the 
cluster’s or component’s volumeCs) of one device type; the 
other part of the DD statement describes the volume that 
contains the catalog recovery area (of another device 
type). 

If the FILE parameter is not specified, an attempt is made 
to dynamically allocate the required volumes. The 
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volumeCs) must be mounted as permanently resident or 
reserved. 

The DD statement you specify must be in the form: 

//ddname DD UNIT=( devtypeC f unitcount3 
// VQL=SER=(volserl,volser2,volser,•••)>••« 

Note: When FILE refers to more than one volume of the same 

device type, the DD statement that describes the volumes 
cannot be a concatenated DD statement. 

FREESPACE( Qlz&&r_Q(zn±l CA^ C M lL t l 1 S. £> 

specifies the amount of space that is to be left free when 
the cluster is loaded and after any split of control 
intervals (Cl-percent) and control areas (CA-percent). 

The amount of empty space in the control interval and 
control area is available for data records that are updated 
and inserted after the cluster is initially loaded. This 
parameter applies only to key-sequenced clusters. 

The amounts are specified as percentages. 

• Cl-percent translates into a number of bytes that is 
equal to, or slightly less than, the percentage value 
of Cl-percent. 

• CA-percent translates into a number of control 
intervals that is equal to, or less than, the 
percentage value of CA-percent. 

Cl-percent and CA-percent, which must be equal to or less 
than 100, can be expressed in decimal (n), hexadecimal 
(X 1 ^), or binary (B f n f ) form. 

When you specify FREESPACEC100 100), one data record is 
placed in each control interval used for data and one 
control interval in each control area is used for data 
(that is, one data record is stored in each control area 
when the data set is loaded). When no FREESPACE value is 
coded, the default specifies that no free space be reserved 
when the data set is loaded. 

When you define the cluster using the RECORDS parameter, 
the amount of free space specified is not taken into 
consideration in the calculations to determine primary 
allocation. 

Abbreviation: FSPC 

IMBED j MI ME D 

specifies whether the sequence set (the lowest level of the 
index) is to be placed with the data component. 

IMBED 

specifies that the sequence-set record for each 
control area is written as many times as it will fit 
on the first track adjacent to the control area. If 
the allocation is less than a cylinder, one track will 
be added to the primary and secondary allocation 
quantities. 

Abbreviation: IMBD 

NOIMBED 

specifies that the sequence-set record for each 
control area is written with the other index records. 

Abbreviation: NIMB D 

The IMBED!NOIMBED parameter interacts with the 

REPLICATE!NOREPLICATE parameter in determining the physical 
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attributes of the index of the cluster. These index 
attributes can be used in the following combinations: 

• The sequence set records are adjacent to the data 
control areas; and only the sequence set records are 
replicated (IMBED and NOREPLICATE). 

• The sequence set records are adjacent to the data 
control intervals/ and all levels of index records are 
replicated (IMBED and REPLICATE). 

• All index records are together/ and all index records 
are replicated (REPLICATE and NOIMBED). 

• All index records are together/ and no index records 
are replicated (NOREPLICATE and NOIMBED). 

For some applications/ specifying index options can improve 
the application*s performance. For information on how the 
index f s optional attributes affect performance/ see VSAM 
M mini a t rra t i imjBMA ri e > 

INDEXED |NONINDEXEDI NUMBERED 

specifies the type of data organization that the cluster is 
to have. 

When a cluster is defined/ you specify whether the data is 
to be indexed (key-sequenced)/ nonindexed (entry 
sequenced)/ or numbered (relative record). 

Certain parameters apply only to key-sequenced clusters/ as 
noted in the description of each of these parameters. 

If you do not specify the data organization and you also do 
not specify the MODEL parameter/ your cluster will default 
to key-sequenced (indexed). 

If you wish to define either an entry-sequenced or relative 
record cluster, you must specify the NONINDEXED or NUMBERED 
parameter unless you specify the MODEL parameter. 

The data organization you select must be consistent with 
other parameters you specify. 

INDEXED 

specifies that the cluster being defined is for 
key-sequenced data. If INDEXED is specified, an index 
component is automatically defined and cataloged. The 
data records can be accessed by key or by relative 
byte address (RBA). 

Abbreviation: IXD 

NONINDEXED 

specifies that the cluster being defined is for 
entry-sequenced data. The data records can be 
accessed sequentially or by relative byte address 
(RBA). 

Abbreviation: NIXD 
NUMBERED 

specifies that the clusters data organization is for 
relative record data. A relative record cluster is 
similar to an entry-sequenced cluster, and has 
fixed-length records that are stored in slots. Empty 
slots hold space for records to be added later. The 
data records are accessed by relative record number 
(slot number). 

Abbreviation: NUMD 
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KEYRANGEStC lowkey hiflhk ffi gl 
C C lowkey highkev ).♦.3) 

specifies that portions of key-sequenced data are to be 
placed on different volumes. Each portion of the data is 
called a key range. This parameter applies only to 
key-sequenced clusters. 

The maximum number of key ranges is 123. Keyranges must be 
in ascending order, and are not allowed to overlap. A gap 
can exist between two key ranges, but you cannot insert 
records whose keys are within the gap. The space to be 
allocated for each key range must be contiguous. 

Keys can contain 1 to 64 characters; 1 to 128 hexadecimal 
characters if coded as X*lowkey* X'highkey*. 

LftWk. ey 

specifies the low key of the key range. If lowkey is 
shorter than the actual keys, it will be padded on the 
right with binary zeros. 

his h k ey 

specifies the high key of the key range. If highkey 
is shorter than the actual keys, it will be padded on 
the right with binary ones. 

The KEYRANGES parameter interacts with other DEFINE CLUSTER 
parameters. You should ensure that your specification of 
KEYRANGES is consistent with the cluster*s other 
attributes. 

• VOLUMES? There should be as many volume serial numbers 
in the volser list as there are key ranges. When a 
volume serial number is duplicated in the volser list, 
more than one key range is allocated space on the 
volume. 

When more than one key range is to be contained on a 
volume, UNIQUE cannot be coded for the cluster*s data 
component. 

When there are more volumes in the volser list than 
there are key ranges, the excess volumes are used for 
overflow records from any key range without 
consideration for key range boundaries. 

When there are fewer volumes in the volser list than 
there are key ranges, the excess key ranges are 
allocated on the last volume specified, and UNIQUE 
cannot also be specified. 

• UNIQUE: When UNIQUE is specified, each key range 
resides on its own volume in its own VSAM data space. 
Other key ranges for the cluster cannot also reside on 
the volume. 

• ORDERED: There is a one-to-one correspondence between 
the volumes in the volser list and the key ranges: The 
first volume on the volser list contains the first key 
range, the second volume contains the second key range, 
and so on. 

If a volume cannot be allocated in the order specified 
by the volser list, your cluster definition job 
terminates with an error message. (For example, the job 
would terminate if there were no space on one of the 
specified volumes.) 

• KEYS: The low key and high key values must not exceed 
the key length specified in the KEY parameter. The KEY 
parameter must be specified in the same component as 
the KEYRANGE parameter. 

Abbreviation: KRNG 



\.y 
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KEVSt,length offset 1M 

specifies information about the prime key field of a 
key-sequenced data set f s data records. This parameter 
applies only to key-sequenced clusters. The default 
specifies a key field of 64 bytes in length, beginning at 
the first byte (byte 0) of each data record. 

The key field of the cluster f s index is called the prime 
key to distinguish it from other keys, called alternate 
keys. For more details on how to specify alternate indexes 
for a cluster, see "DEFINE ALTERNATEINDEX" on page 62. 

When the data record is allowed to span control intervals, 
the record's key field must be within the part of the 
record that is in the first control interval. 

lAD fljfc h Sl ffS£± 

specifies the length of the key and its displacement 
Cin bytes) from the beginning of the record. The sum 
of length plus offset cannot exceed the length of the 
shortest record. 

The length of the key can be 1 to 255 bytes. Length 
and offset can be expressed in decimal (n), 
hexadecimal (X'n 1 ), or binary (B'n 1 ) form. 

MASTERPW(ms§wgrd) 

specifies a master password for the entry being defined. 

The master password allows all access method services 
operations against the cluster entry and its data and index 
entries, and allows the user's program to access the 
cluster's contents without restriction. For more details 
on how passwords can be used, see "Security Protection" in 

The AUTHORIZATION, CODE, and ATTEMPTS parameters have no 
effect unless the entry has a master password associated 
with it. If MASTERPW is not specified, the highest-level 
password specified becomes the password for all higher 
levels. 

Abbreviation: MRPW 

MOD E L (fintlim a flj ft E /fiasSMard 3 
C c<jf p a m e C / M S S W.Q.cd 3 3) 

specifies an existing entry to be used as a model for the 
entry being defined. 

You can use an existing cluster f s entry as a model for the 
attributes of the cluster being defined. For details about 
how a model is used, see £ g±alo g^A. dm i ni ^.ina t iP,n.-.O.M % ris . 

You may use some attributes of the model and override 
others by explicitly specifying them in the definition of 
the cluster or component. If you do not want to add or 
change any attributes, specify only the entry type 
(cluster, data, or index) of the model to be used and the 
name of the entry to be defined. 

Unless another entry is specified with the MODEL parameter 
as a subparameter of DATA or INDEX, when you use a cluster 
entry as a model for the cluster, the data and index 
entries of the model cluster are used as models for the 
data and index components of the cluster still to be 
defined. 

e Mry p a mg . 

specifies the name of the cluster or component entry 
to be used as a model. 

JB&g-SHQrjd 

specifies a password. If the model entry is 
password-protected and it is cataloged in a 
password-protected catalog, you must supply the read- 
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or higher-level password of either the model entry or 
its catalog. If both passwords are supplied* the 
catalog’s password is used. RACF: The read or higher 
RACF authority to the model or catalog is required. 

If you are not specifying new protection attributes 
for the cluster (that is* the model’s passwords and 
protection attributes are being copied)* you must 
supply the master password of either the model entry 
or its catalog. RACF: The alter RACF authority to the 
model or catalog is required. 


names the model entry’s catalog. You identify the 
catalog that contains the model entry for either of 
these cases: 


• You specify the catalog f s password instead of the 
model entry’s password. 

• The model entry’s catalog is not identified with a 
JOBCAT or STEPCAT DD statement* and is not the 
master catalog. 

If the catalog’s volume is physically mounted* it is 
dynamically allocated. The volume must be mounted as 
permanently resident or reserved. For information 
about the order in which a catalog is selected when 
the catalog’s name is not specified* see "Order of 
Catalog Selection for DEFINE” on page 16. 

ORDERED | yNO.RMR.HP 

specifies whether volumes are to be used in the order in 
which they are listed in the VOLUMES parameter. 

ORDERED 

specifies that the volumes are to be used in the order 
in which they are listed for the VOLUMES parameter. 

When you want each key range to reside on a separate 
volume* you can use ORDERED so that the first key 
range goes on the first volume* the second key range 
goes on the second volume* and so on. 

If ORDERED is specified and the volumes cannot be 
allocated in the order specified* the command is 
terminated. (For example* the command would terminate 
if there were no space on one of the volumes 
specified.) 

Abbreviation: QRD 

UNORDERED 

specifies no order for the use of the volumes 
specified in the VOLUMES parameters. 

Abbreviation: UNORD 

OWNER(p M O eric P 

specifies the identification of the cluster’s owner. 

Note to TSO Users: If the owner is not identified with the 
OWNER parameter* the TSO user’s userid becomes the ownerid. 

READ PW ( password ) 

specifies a read password for the entry being defined. The 
read password permits read operations against the entry’s 
records. 

Abbreviation: RDPW 

RECORDS I ZE( aye, ma xi mum I default) 

specifies the average and maximum lengths* in bytes* of the 
records in the data component. 
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RECORDSIZE can be specified as a parameter of either 
CLUSTER or DATA. 

average and maximum are integer values and can be expressed 
in decimal (n), hexadecimal (X'n*), or binary (B'n 1 ) form. 
The minimum record size that you can specify is one byte. 

For nonspanned records, the maximum record size + 7 cannot 
exceed the data component's control interval size (that is, 
the maximum nonspanned record size, 32 761 + 7 equals the 
maximum data component control interval size, 32 768). 

For spanned records, the maximum record size cannot exceed 
the number of control intervals per control area times the 
quantity control interval size less 10, as calculated by 
VSAM. When you specify a record size that is larger than 
one control interval, you must also specify spanned records 
(SPANNED). 

You can identify the records as fixed length by specifying 
the same value for average and maximum. If NUMBERED is 
also specified, the records must be fixed length (that is, 
average equals maximum). 

When your records are fixed length, you can use the 
following formula to find a control interval size that 
contains a whole number (n) of records: 

CISZ = (n x RECSZ) + 10 

or 

n = 

RECSZ 

When SPANNED or NUMBERED is specified: 

CISZ =(n x (RECSZ + 3)) + 4 


or 


n 


(RECSZ + 3) 


where: 

• n is the number of fixed-length records in a control 
interval, and is a positive integer. 

• CISZ is the control interval size (see 
CONTROLINTERVALSIZE parameter). 

• RECSZ is the average record size. 

■default 

when SPANNED is specified, the default is 
RECORDSIZE(4086 32600). Otherwise, the default is 
RECORDSIZE(4089 4089). 

Caution: When you specify RECORDS, you should ensure that: 

REC(sec) x RECSZ(avg) > RECSZ(max) 

where: 

• REC(sec) is the secondary space allocation quantity, in 
records. 

• RECSZ(avg) is the average record size (default = 4086 
or 4089 bytes). 

• RECSZ(max) is the maximum record size (default = 4089 
or 32600 bytes). 
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When the SPANNED record size default prevails (32600 
bytes)/ the secondary allocation quantity should be at 
least 8 records. 


Note: REPRO and EXPORT will not support data sets with 

record sizes greater than 32760. 

Abbreviation: RECSZ 

REPLICATE | NOREEUfiAIE 

specifies how many times each index record is to be written 
on a track. 

REPLICATE 

specifies that each index record is to be written on a 
track as many times as it will fit. With REPLICATE/ 
rotational delay is reduced and performance is 
improved. However/ the cluster's index usually 
requires more direct access device space. 

This parameter applies only to key-sequenced clusters. 

Abbreviation: R EP L 

NOREPLICATE 

specifies that the index records are to be written on 
a track only one time. 

Abbreviation: N R EP L 

For a discussion of the relationship between IMBEDINOIMBED 
and REPLICATEINOREPLICATE/ see the description of the 
IMBEDINOIMBED parameter. 

REUSE IMRIMSE 

specifies whether the cluster can be opened again and again 
as a reusable cluster. 

REUSE 

specifies that the cluster can be opened again and 
again as a reusable cluster. When a reusable cluster 
is opened/ its high-used RBA is set to zero if you 
open it with an access control block that specifies 
the RESET attribute. 

REUSE allows you to create an entry-sequenced/ 
key-sequenced/ or relative record work file. 

When you create a reusable cluster/ you cannot build 
an alternate index to support it. Also/ you cannot 
create a reusable cluster with key ranges (see the 
KEYRANGE parameter) or with its own data space (see 
the UNIQUE parameter). Reusable data sets may be 
multivolume and are restricted to 16 physical extents 
per volume. 

Abbreviation: RUS 

NOREUSE 

specifies that the cluster cannot be opened again as a 
new cluster. 

Abbreviation: NRUS 

SHAREOPTIQNSCscasscaaiant ^oa s s y.s.teiTiI II 3) 

specifies how a component or cluster can be shared among 
users. For a description of data set sharing/ see VSAM 

tj, , q n ... Q u jds * To ensure integrity, you should be 
sure that share options specified at the DATA and INDEX 
levels are the same. 

£rj> jssn& g lpn 

specifies the amount of sharing allowed among regions 
within the same system or within multiple systems 
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using global resource serialization (GRS). 

Independent job steps in an operating system or 
multiple systems using GRS can access a VSAM data set 
concurrently. The values that can be specified are: 

1 

specifies that the data set can be shared by any 
number of users for read processing, or the data 
set can be accessed by only one user for read and 
write processing. With this option, VSAM ensures 
complete data integrity for the data set. 

2 

specifies that the data set can be accessed by 
any number of users for read processing and it 
can also be accessed by one user for write 
processing. 

With this option, VSAM ensures write integrity by 
obtaining exclusive control for a control 
interval when it is to be updated. If a user 
desires read integrity, it is that user's 
responsibility to use the ENQ and DEQ macros 
appropriately to provide read integrity for the 
data the program obtains. (For information on 
using ENQ and DEQ, see System Macros and 
£ac jli±Le.s.) 

3 

specifies that the data set can be fully shared 
by any number of users. With this option, each 
user is responsible for maintaining both read and 
write integrity for the data the program 
accesses. 

User programs that ignore the write integrity 
guidelines can cause VSAM program checks, lost or 
inaccessible records, uncorrectable data set 
failures, and other unpredictable results. This 
option places heavy responsibility on each user 
sharing the data set. 

4 

specifies that the data set can be fully shared 
by any number of users and buffers used for 
direct processing are refreshed for each request. 

This option requires your program to use the ENQ 
and DEQ macros to maintain data integrity while 
sharing the data set. Improper use of the ENQ 
macro can cause problems similar to those 
described under SHAREOPTIONS 3. (For information 
on using ENQ and DEQ, see S YSl m JifetCC -Q S .jm d 
EasiJliies.) 

&C.PSSS yst e m 

specifies the amount of sharing allowed among systems. 
Job steps of two or more operating systems can gain 
access to the same VSAM data set regardless of the 
disposition specified in each step*s DD statement for 
the data set. 

To get exclusive control of the data set f s volume, a 
task in one system issues the RESERVE macro. The 
level of cross-system sharing allowed by VSAM applies 
only in a multiple operating system environment. The 
values that can be specified are: 

1 

Reserved 

2 

Reserved 
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3 

specifies that the data set can be fully shared. ^ 

With this option, each user is responsible for 
maintaining both read and write integrity for the V 
data that user*s program accesses. 

User programs that ignore write integrity 
guidelines can cause VSAM program checks, 
uncorrectable data set failures, and other 
unpredictable results. This option places heavy 
responsibility on each user sharing the data set. 

4 

specifies that the data set can be fully shared. 

Buffers used for direct processing are refreshed 
for each request. 

This option requires that you use the RESERVE and 
DEQ macros to maintain data integrity while 
sharing the data set. (For information on using 

RESERVE and DEQ, see S ysAen u M3 .sr p .Si. a n d 

Facilities .) Writing is limited to PUT-update 
and PUT-insert processing that does not change 
the high-used RBA if your program opens the data 
set with DISP=SHR. 

Data set integrity cannot be maintained unless 
all jobs accessing the data set in a cross-system 
environment specify DISP=SHR. Improper use of 
the RESERVE macro can cause problems similar to 
those described under SHAREOPTIONS 3. 

To ensure data integrity in a shared environment, VSAM 
provides users of SHAREOPTIONS 4 (cross-region and 
cross-system) with the following assistance: 

• Each PUT request results in the appropriate buffer(s) 
being written immediately to the VSAM cluster f s direct 
access device space (that is, the buffer in the user f s 
address space that contains the new or updated data 
record, and the buffers that contain new or updated 
index records when the user's data is key sequenced.) 

• Each GET request results in all the user's input 
buffers being refreshed. The contents of each data and 
index buffer being used by the user's program are 
retrieved from the VSAM cluster's direct access device. 

Abbreviation: SHR 

SPANNED I NPNSPANNE P 

specifies whether a data record is allowed to cross control 
interval boundaries. 

SPANNED 

specifies that, if the maximum length of a data record 
(as specified with RECORDSIZE) is larger than a 
control interval, the record will be contained on more 
than one control interval. This allows VSAM to select 
a control interval size that is optimum for the direct 
access device. 

When a data record that is larger than a control 
interval is put into a cluster that allows spanned 
records, the first part of the record completely fills 
a control interval. Subsequent control intervals are 
filled until the record is written into the cluster. 

Unused space in the record's last control interval is 
not available to contain other data records. 

Abbreviation: SPND 
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NONSPANNED 

specifies that the record must be contained in one 
control interval. VSAM will select a control interval 
size that accommodates your largest record. 

Abbreviation: NSPND 

SPEED lBE£.QyJEY 

specifies whether storage allocated to the data component 
is to be preformatted before records are inserted. 

SPEED|RECOVERY applies only to initial loading. 

When you specify RECOVERY, your initial load takes longer 
because the control areas are written initially with 
end-of-file indicators and again with your data records. 
When you specify SPEED, your initial load is quicker. 

SPEED 

specifies that the data components space is not 
preformatted. Its space might contain data records 
from a previous use of the space, or it might contain 
binary zeros (its contents are unpredictable). 

If the initial load fails, you must load the data 
records again from the beginning, because VSAM is 
unable to determine where your last correctly written 
record is. (VSAM cannot find a valid end~of-file 
indicator when it searches your data records.) 

RECOVERY 

specifies that the data component's control areas are 
written with records that indicate end of file. When 
a data record is written (during the initial load) 
into a control interval, it is always followed by a 
record that identifies the record that has just been 
written as the last record in the cluster. 

If the initial load fails, you can resume loading data 
records after the last correctly written data record, 
because an end-of-file indicator identifies it as the 
last record. 

Abbreviation: RCVY 

STAGE |BIND ICYLINDERFAULT 

specifies how a cluster or component that is stored on a 
mass storage volume is to be staged. 

When the cluster or component is not stored on a mass 
storage volume, the attribute is ineffective until the 
direct access storage volume on which the cluster or 
component is stored is converted to a mass storage volume. 
The CONVERTV command used in this conversion is described 
in 

Inform ation . 

When one of these parameters is specified for the data 
component and another parameter is specified for the index 
component, the components are staged separately as 
specified, except when the sequence set of the index 
component is embedded in the data. In that case, the 
parameter specified for the index component applies to both 
components. 

STAGE 

indicates that the cluster or component is to be 
staged from mass storage to a direct access storage 
staging drive when the cluster or component is opened. 
If the cluster or component cannot be staged at open 
time because of heavy staging activity of other 
objects, data is staged as the processing program 
needs it. 
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BIND 

indicates that the cluster or component is not only to 
be staged^ but also to be bound; that is, it is to be 
retained on the direct access storage staging drive 
until it is closed. If the cluster or component 
cannot be staged at open time because of heavy staging 
activity of other objects/ data is staged as the 
processing program needs it. 

CYLINDERFAULT 

indicates that the cluster or component is not to be 
staged when it is opened, but that data from it is to 
be staged as the processing program needs it. 

Abbreviation: CYL F 

T0( date )1F0R( davs ) 

specifies the retention period for the cluster being 
defined. If neither TO nor FOR is specified, the cluster 
can be deleted at any time. 

TO (da±e) 

specifies the date, in the form yyddd, where yy is the 
year and ddd is the number (001 through 365) of the 
day through which the cluster being defined is to be 
kept. 

FORCduys) 

specifies the number of days for which the cluster 
being defined is to be kept. The maximum number that 
can be specified is 9999. If the number specified is 
0 through 1330, the cluster is retained for the number 
of days specified; if the number is between 1831 and 
9999, the cluster is retained through the year 1999. 


can be expressed in decimal (n)/ hexadecimal 
(X’n 1 )/ or binary (B'n') form. 

UNIQUE j gjJBALLOmilON 

specifies whether the cluster's components are allocated an 
amount of space from the volume's available space (UNIQUE) 
or from a VSAM data space's available space 
(SUBALLOCATION). 

UNIQUE 

specifies that a VSAM data space is to be built and 
assigned exclusively to each component of the cluster. 
The data space is created when the cluster is defined. 
The cluster's volume(s) must be mounted. VSAM builds 
a DSCB in the volume's table of contents (VTOC) to 
describe the data space. The name of the data space/ 
which is the same as the component's name, is put in 
the DSCB. A subentry is added to the volume entry (in 
the VSAM catalog) to describe the VSAM data space. 

Abbreviation: UNQ 

SUBALLOCATION 

specifies that space from one of the VSAM data spaces 
on the volume is assigned to the cluster's components. 

Abbreviation: SUBAL 

The space allocation attribute interacts with other DEFINE 
CLUSTER parameters. You should ensure that the space 
allocation attribute you specify for the cluster is 
consistent with other attributes: 

• REUSE: You cannot specify REUSE when you specify UNIQUE 
for a cluster or its components. 
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• KEYRANGES: When UNIQUE is specified/ a data space is 
built and allocated for each key range. Each key range 
is on a separate volume. 

• VOLUMES: When UNIQUE is not specified/ VSAM data space 
must exist on the volume that is to contain the 
cluster's component. When UNIQUE is specified/ and 
more than one volume is specified/ VSAM must already 
own all the volumes except the first. If there is no 
VSAM space on a volume/ you must execute a DEFINE SPACE 
CANDIDATE before your DEFINE UNIQUE. 

UPDATEPWt password ) 

specifies an update password for the entry being defined. 
The update password permits read and write operations 
against the entry's records. 

If a read password is the only password specified for the 
object (that is/ it is the highest-level password)/ it 
propagates upward and becomes the password for all higher 
levels. If you specify a highei—level password and do not 
specify an update password/ the update password is null. 

Abbreviation: UPDPW 

WRITECHECK I NOWRXTEOHECK 

specifies whether the cluster or component is to be checked 
by a machine action called write check when a record is 
written into it. 

WRITECHECK 

specifies that a record is written and then read, 
without data transfer/ to test for the data check 
condition. 

Abbreviation: WCK 

NOWRITECHECK 

specifies that the cluster or component is not to be 
checked by a write check. 

Abbreviation: NWCK 


DATA AND INDEX COMPONENTS OF A CLUSTER 

Attributes can be specified separately for the cluster's data 
and index components. The DATA and INDEX parameters are listed 
at the beginning of this section. These parameters are 
described in detail as parameters of the cluster as a whole. 
Restrictions are noted with each parameter's description. 
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Define a Key-Sequenced Cluster Specifying Data and Index Parameters: Example 1 

In this example, a key sequenced cluster is defined. The DATA 
and INDEX parameters are specified and the cluster f s data and 
index components are explicitly named. This example assumes 
that, if the cluster is being defined in a VSAM catalog, a VSAM 
data space exists on volume VSER02. It also assumes that an 
alias name D40 has been defined for the catalog D27UCAT1. This 
naming convention causes D4G.MYDATA to be cataloged in D27UCAT1. 

//DEFCLU1 JOB 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYS0UT=A 

//SYSIN DD X 

DEFINE CLUSTER - 

(NAMECD40.MYDATA) - 
VOLUMESCVSERQ2) - 
RECORDSC1000 500)) - 
DATA - 

(NAMECD40.KSDATA) - 
KEYSC15 0) - 
RECORDSIZEC250 250) - 
FREESPACEC20 10) - 
BUFFERSPACEC25000) ) - 
INDEX - 

(NAMECD40.KSINDEX) - 
IMBED) - 

CATALOG (D27UCAT1/USERUPPW) 

/x 

The DEFINE CLUSTER command builds a cluster entry, a data entry, 
and an index entry to define the key sequenced cluster 
D40.MYDATA. The parameters specified for the cluster as a whole 
are: 

• NAME, which specifies that the cluster's name is D40.MYDATA. 

• VOLUMES, which specifies that the cluster is to reside on 
volume VSER02. 

• RECORDS, which specifies that the clusters space allocation 
is 1000 data records. When the cluster is extended, it is 
extended in increments of 500 records. After the space is 
allocated, VSAM calculates the amount required for the index 
and subtracts it from the total. 

In addition to the parameters specified for the cluster as a 
whole, DATA and INDEX parameters specify values and attributes 
that apply only to the clusters data or index component. The 
parameters specified for the data component of D40.MYDATA are: 

• NAME, which specifies that the data components name is 
D40.KSDATA. 

• KEYS, which specifies that the length of the key field is 15 
bytes and that the key field begins in the first byte (byte 
0) of each data record. 

• RECORDSIZE, which specifies fixed-length records of 250 
bytes. 

• BUFFERSPACE, which specifies that a minimum of 25 000 bytes 
must be provided for I/O buffers. A large area for I/O 
buffers can help to improve access time with certain types 
of processing. For example, with direct processing if the 
high-level index can be kept in virtual storage, access time 
is reduced. With sequential processing, if enough I/O 
buffers are available, VSAM can perform a read-ahead thereby 
reducing system overhead and minimizing rotational delay. 
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• FREESPACE, which specifies that ZOZ of each control interval 
and 10% of each control area are to be left free when 
records are loaded into the cluster. After the cluster f s 
records are loaded, the free space can be used to contain 
new records. 

The parameters specified for the index component of D40.MYDATA 

are: 

• NAME, which specifies that the index components name is 
D40.KSINDEX. 

• IMBED, which specifies that sequence-set index records are 
to be placed in the data components control areas (the 
sequence-set records will be replicated automatically). 

The parameter which provides the catalog f s password is: 

• CATALOG, which specifies the catalog name and its update 
password. This parameter would not be necessary if Cl) the 
catalog was not password protected, and (2) D40 was defined 
as the catalog*s alias. 


Define a Key-Sequenced Cluster and an Entry-Sequenced Cluster: Example 2 

In this example, two VSAM clusters are defined. The first 
DEFINE command defines a key sequenced VSAM cluster, 

D40.EXAMPLE.KSDS1. The second DEFINE command defines an 
entry-sequenced VSAM cluster, D50.EXAMPLE.ESDS1. In both 
examples, it is assumed that alias names, D40 and D50, have been 
defined for user catalogs D27UCAT1 and D27UCAT2, respectively, 
and that neither user catalog is password-protected. This 
example assumes that VSAM data space that can contain the data 
sets already exists on volumes VSER02 and VSER03. 

//DEFCLU2 JOB 

//STEP1 EXEC PGM=IDCAM$ 

//SYSPRINT DD SYSQUT=A 

//SYSIN DD X 

DEFINE CLUSTER - 

(NAMECD40.EXAMPLE.KSDS1) - 
MODEL(D40.MYDATA) - 
VOLUMESCVSER02) - 
NOIMBED ) 

DEFINE CLUSTER - 

CNAMECD50.EXAMPLE.ESDS1) - 
RECORDSCIOO 500) - 
RECORDSIZEC250 250) - 
VOLUMESCVSER03) - 
NONINDEXED ) 

/x 

The first DEFINE command builds a cluster entry, a data entry, 
and an index entry to define the key sequenced cluster 
D40.EXAMPLE.KSDS1. Its parameters are: 

• NAME, which specifies the name of the key sequenced cluster, 
D40.EXAMPLE.KSDS1. The cluster will be defined in the user 
catalog for which D40 has been established as an alias. 

• MODEL, which identifies D40.MYDATA as the cluster to use as 
a model for D40.EXAMPLE.KSDS1. The attributes and 
specifications of D40.MYDATA that are not otherwise 
specified with the DEFINE command*s parameters are used to 
define the attributes and specifications of 

D40.£XAMPLE.KSDS1. D40.MYDATA is located in the user 

catalog for which D40 has been established as an alias. 

• VOLUMES, which specifies that the cluster is to reside on 
volume VSER02. 
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• NOIMBED, which specifies that space is not to be allocated 
for sequence-set control intervals within the data 
component's physical extents. 

The second DEFINE command builds a cluster entry and a data 

entry to define an entry-sequenced cluster, D50.EXAMPLE.ESDS1• 

Its parameters are: 

• NAME, which specifies the name of the entry-sequenced 
cluster, D50.EXAMPLE.ESDS1. The cluster will be defined in 
the user catalog for which D50 has been established as an 
alias. 

• RECORDS, which specifies that the cluster's space allocation 
is 100 records. When the cluster is extended, it is 
extended in increments of 500 records. 

• RECORDSIZE, which specifies that the cluster's records are 
fixed length (the average record size equals the maximum 
record size) and 250 bytes long. 

• VOLUMES, which specifies that the cluster is to reside on 
volume VSER03. 

• NONINDEXED, which specifies that the cluster is to be an 
entry-sequenced cluster. 


Define a Key-Sequenced Cluster (in a Unique Data Space) in a VSAM Catalog: Example 3 

In this example, a key sequenced cluster is defined. The 
cluster is unique; that is, it is the only cluster in a VSAM 
data space. 


//DEFCLU3 

JOB 

... 

//STEP1 

EXEC 

PGM=IDCAMS 

//SYSPRINT 

DD 

SYS0UT=A 

//V0L4 

DD 

VOL=SER=VSEROA,UNIT=DISK,DISP=OLD 

//SYSIN 

DD 

X 


DEFINE CLUSTER - 

(NAMEC ENTRY) - 
RECORDSIZEC80 80) - 
FILECV0L4) - 
KEYSC10 10) - 
VOLUMESCVSER04) - 
UNIQUE - 

CYLINDERSC5 10) ) - 

CATALQGCUSERCAT3) 

/x 

The DEFINE CLUSTER command builds a cluster entry, a data entry, 
and an index entry to define the key sequenced cluster ENTRY. 

The DEFINE CLUSTER command also allocates a data space and 
allocates it for the cluster's exclusive use. The command's 
parameters are: 

• NAME, which specifies the cluster's name is ENTRY. 

• RECORDSIZE, which specifies that the records are fixed 
length, 80-byte records. 

• FILE, which specifies the name of a DD statement that 
describes the cluster's volume and causes it to be mounted. 
The volume must be mounted so that VSAM can record the 
format-1 DSCBs of the key sequenced cluster in the volume's 
VTOC. If FILE is not specified, an attempt is made to 
dynamically allocate the volume. 

• KEYS, which specifies that the length of the key field is 10 
bytes and that the key field begins in the 11th byte (byte 
10) of each data record. 
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• VOLUMES and UNIQUE/ which specify that ENTRY is to reside 
alone in a data space on volume VSERQ4. Access method 
services will create two data spaces for the cluster: one 
for the data component/ and one for the index. Both data 
spaces are to be on volume VSER04. This example assumes 
that volume VSER04 has enough available space to contain the 
new data space. This example also assumes that either the 
volume f s entry is in the MYCAT catalog or that volume VSER04 
is not owned by a VSAM catalog at the beginning of the job. 

• CYLINDERS/ which specifies that five cylinders are allocated 
for the cluster’s data space. When the cluster's data or 
index component is extended, the component is to be extended 
in increments of 10 cylinders. 

• CATALOG, which specifies the name of the catalog into which 
the cluster will be defined. In this example, USERCAT3 is 
not password-protected and an attempt will be made to 
dynamically allocate it. 


Define a Relative Record Cluster in a Catalog: Example 4 

In this example, a relative record cluster is defined. The 
cluster is suballocated Cit can reside in a VSAM data space with 
other VSAM objects). Volume VSER01 does not have to be mounted 
or allocated at this time. 

//DEFCLU4 JOB 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYS0UT=A 

//SYSIN DD X 

DEFINE CLUSTER - 

(NAMECEXAMPLE.RRDS1) - 
RECORDSIZECIOO 100) - 
VOLUMESCVSER01) - 
TRACKSC10 5) - 
NUMBERED) - 

CATALOGC USERCAT/USERUPPW) 

/x 

The DEFINE CLUSTER command builds a cluster entry and a data 
entry to define the relative record cluster, EXAMPLE.RRDS1 in 
the user catalog. The DEFINE CLUSTER command also obtains space 
for the cluster from the VSAM data space on volume VSER01, and 
allocates 10 tracks for the cluster's use. The command's 
parameters are: 

• NAME, which specifies that the cluster's name is 
EXAMPLE.RRDS1. 

• RECQRDSIZE, which specifies that the records are fixed 
length, 100-byte records. Average and maximum record length 
must be equal for a relative record data set. 

• VOLUMES, which specifies that the cluster is to reside on 
volume VSER01. This example assumes that the volume is 
already cataloged in the user catalog, USERCAT. 

• TRACKS, which specifies that ten tracks are to be allocated 
for the cluster. When the cluster is extended, it is to be 
extended in increments of 5 tracks. 

• NUMBERED, which specifies that the cluster's data 
organization is to be relative record. 

• CATALOG, which supplies the user catalog's update password, 
USERUPPW. 
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Define a Reusable Entry-Sequenced Cluster in a Catalog: Example 5 

In this example, a reusable entry-sequenced cluster is defined. 
The cluster can be used as a temporary data set. Each time the 
cluster is opened, its high-used RBA can be reset to zero. The 
cluster is suballocated (that is, it can reside in a VSAM data 
space with other VSAM objects). 

//DEFCLU5 JOB 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYS0UT=A 

//SYSIN DD * 

DEFINE CLUSTER - 

(NAMECEXAMPLE.ESDS2) - 
RECORDSIZEC2500 3000) - 
SPANNED - 
VOLUMESCVSER03) - 
CYLINDERSC2 1) - 
NONINDEXED - 
REUSE - 

MASTERPWCESD2MRPW) - 
UPDATEPWCESD2UPPW) ) - 
CATAL0GCD27UCAT2/USERMRPW) 

/X 

The DEFINE CLUSTER command builds a cluster entry and a data 
entry to define the entry-sequenced cluster, EXAMPLE.ESDS2. The 
DEFINE CLUSTER command also obtains space for the cluster from 
one of the Class 1 VSAM data spaces on volume VSER03, and 
assigns ten tracks for the cluster*s use. VSER03 does not have 
to be mounted or allocated at this time. The command^ 
parameters are: 

• NAME, which specifies that the clusters name is 
EXAMPLE.ESDS2. 

• RECORDSIZE, which specifies that the records are 
variable-length, with an average size of 2500 bytes and a 
maximum size of 3000 bytes. 

• SPANNED, which specifies that data records can cross control 
interval boundaries. 

• VOLUMES, which specifies that the cluster is to reside on 
volume VSER03. This example assumes that the volume is 
already cataloged in the user catalog, D27UCAT2. 

• CYLINDERS, which specifies that two cylinders are to be 
allocated for the cluster f s space. When the cluster is 
extended, it is to be extended in increments of one 
cylinder. 

• NONINDEXED, which specifies that the cluster*s data 
organization is to be entry sequenced. This parameter 
overrides the INDEXED parameter. 

• REUSE, which specifies that the cluster is to be reusable. 
Each time the cluster is opened, its high-used RBA can be 
reset to zero and it is effectively an empty cluster. 

• MASTERPW and UPDATEPW, which specifies the master password, 
ESD2MRPW, and the update password, ESD2UPPW, for the 
cluster. 

• CATALOG, which specifies that the cluster is to be defined 
in a user catalog, D27UCAT2. The example also supplies the 
user catalog's master password, USERMRPW. 
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Define a Key-Sequenced Cluster in a Catalog: Example 6 

In this example, a key sequenced cluster is defined* In other 
examples, an alternate index is defined over the cluster, and a 
path is defined that relates the cluster to the alternate index. 
The cluster, its alternate index, and the path entry are all 
defined in the same catalog, USERRCAT. 

//DEFCLU6 JOB 

//STEP1 EXEC PGM=IDCAM$ 

//SYSPRINT DD SYS0UT=A 

//SYSIN DD * 

DEFINE CLUSTER - 

(NAME(EXAMPLE.KSDS2)) - 
DATA - 

(MASTERPW(DAT2MRPW) - 
UPDATEPWCDAT2UPPW) - 
READPW(DAT2RDPW) - 
RECORDSC500 100) - 
EXCEPTIONEXITCDATEXIT) - 
ERASE - 

FREESPACEC20 10) - 
KEYSC6 4) - 
REC0RDSIZEC80 100) - 
VOLUMESCVSER01) ) - 
INDEX - 

(MASTERPW(IND2MRPW) - 
UPDATEPW(IND2UPPW) - 
READPWCIND2RDPW) - 
RECORDSC300 300) - 
IMBED - 

VOLUMESCVSER01) ) - 
CATALOGC USERCAT/USERUPPW) 

/x 

The DEFINE CLUSTER command builds a cluster entry, a data entry, 
and an index entry to define the key sequenced cluster, 

EXAMPLE.KSDS2. The DEFINE CLUSTER command also obtains space 
for the cluster from one of the VSAM data spaces on volume 
VSER01, and allocates space separately for the cluster’s data 
and index components. Because the cluster is being defined into 
a recoverable catalog, an attempt will be made to dynamically 
allocate the catalog recovery area on VSER01. 

The command’s parameter that applies to the cluster is: 

• NAME, which specifies that the cluster’s name is 
EXAMPLE.KSDS2. 

The command’s parameters that apply only to the cluster’s data 
component are enclosed in the parentheses following the DATA 
keyword: 

• MASTERPW, UPDATEPW, and READPW, which specify the data 
component’s master password, DAT2MRPW, update password, 
DAT2UPPN, and read password, DAT2RDPW. 

• RECORDS, which specifies that an amount of tracks equal to 
at least 500 records is to be allocated for the data 
component’s space. When the data component is extended, it 
is to be extended in increments of tracks equal to 100 
records. 

• EXCEPTIONEXIT, which specifies the name of the exception 
exit routine, DATEXIT that is to be processed if an I/O 
error occurs while a data record is being processed. 

• ERASE, which specifies that the cluster’s data is to be 
erased (overwritten with binary zeros) when the cluster is 
deleted. 

• FREESPACE, which specifies the amounts of free space to be 
left in the data component’s control intervals (20%) and the 
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control areas (102 of the control intervals in the control 
area) when data records are loaded into the cluster. 


• KEYS, which specifies the location and length of the key 
field in each data record. The key field is 6 bytes long 
and begins in the 5th byte (byte 4) of each data record. 

• RECORDSIZE, which specifies that the clusters records are 
variable length, with an average size of 80 bytes and a 
maximum size of 100 bytes. 

• VOLUMES, which specifies that the cluster is to reside on 
volume VSER01. This example assumes that the volume is 
already cataloged in the catalog, USERCAT. 

The command f s parameters that apply only to the cluster f s index 

component are enclosed in the parentheses following the INDEX 

keyword: 

• MASTERPW, UPDATEPW, and READPW, which specifies the index 
components master password, IND2MRPW, update password, 
IND2UPPW, and read password, IND2RDPW. 

• RECORDS, which specifies that an amount of tracks equal to 
at least 300 records is to be allocated for the index 
components space. When the index component is extended, it 
is to be extended in increments of tracks equal to 300 
records. 


A, 


• IMBED, which specifies that the indexS sequence set records 
are to be placed in the data components control areas (the 
sequence set records will be replicated automatically). 

• VOLUMES, which specifies that the index component is to 
reside on volume VSER01. 

The CATALOG parameter supplies the catalogs update password. 


Define an Entry-Sequenced Cluster Using a Model: Example 7 

In this example, two entry-sequenced clusters are defined. The 
attributes of the second cluster defined is modeled from the 
first cluster. 


//DEFCLU7 

JOB 

# • « 

//STEP 1 

EXEC 

PGM=IDCAMS 

//STEPCAT 

DD 

DSNAME=USERCAT4,DISP=SHR 

//SYSPRINT 

DD 

SYS0UT=A 

//SYSIN 

DD 

X 


DEFINE CLUSTER - 

(NAME(GENERIC.A.BAKER) - 
V0LUMES(VSER02) - 
RECORDSdOO 100) - 
RECORDSIZE(80 80) - 
NONINDEXED ) - 
CATAL0G(USERCAT4/USERMRPW) 

DEFINE CLUSTER - 

(NAME(GENERIC.B.BAKER) - 
MODEL(GENERIC.A.BAKER USERCAT4)) - 
CATAL0G(USERCAT4/USERMPRW) 

/x 

Job control language statement: 

• STEPCAT DD, which makes a catalog available for this job 
step: USERCAT4. 


The first DEFINE CLUSTER command defines an entry-sequenced # 

cluster, GENERIC.A.BAKER. Its parameters are: 

• NAME, which specifies the name of the entry-sequenced 
cluster, GENERIC.A.BAKER. 
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• VOLUMES/ which specifies that the cluster is to reside on 
volume VSER02. 

• RECORDS/ which specifies that the clusters space allocation 
is 100 records. When the cluster is extended/ it is 
extended in increments of 100 records. 

• RECORDSIZE/ which specifies that the cluster's records are 
fixed length (the average record size equals the maximum 
record size) and 80 bytes long. 

• NONINDEXED/ which specifies that the cluster is entry 
sequenced. 

• CATALOG/ which specifies that the cluster is to be defined 
in the USERCAT4 catalog. The master password of USERCAT4 is 
USERMRPW. 

The second DEFINE CLUSTER command uses the attributes and 

specifications of the previously defined cluster/ 

GENERIC.A.BAKER/ as a model for the cluster still to be defined/ 

GENERIC.B.BAKER. Its parameters are: 

• NAME/ which specifies the name of the entry-sequenced 
cluster, GENERIC.B.BAKER. 

• MODEL, which identifies GENERIC.A.BAKER, cataloged in user 
catalog D27UCAT1, as the cluster to use as a model for 
GENERIC.B.BAKER. The attributes and specifications of 
GENERIC.A.BAKER that are not otherwise specified with the 
DEFINE command's parameters are used to define the 
attributes and specifications of GENERIC.B.BAKER. 

• CATALOG, which specifies that the cluster is to be defined 
in the USERCAT4 catalog. The master password of USERCAT4 is 
USERMRPW. 
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The DEFINE GENERATIONDATAGROUP command creates a catalog entry 
for a generation data group. The format of this command is: 


DEFINE 


GENERATIONDATAGROUP 
(NAME( entrvname ) 
LIMITC limit ) 

c empty mm mi 

EQWNERC ownend ) 3 
l SCRATCH I NOSCRATCH 3 
C TO C dg,t.g) I FOR(da^s 3 3) 


t CAT A LOG (c at D.a.n). e l 3 * 3 


DEFINE can be abbreviated: DEF 


DEFINE GENERATIONDATAGROUP PARAMETERS 


Required Parameters 


GENERATIONDATAGROUP 

specifies that a generation data group entry is to be 
defined. 

Abbreviation: GDG 
NAMEtejitnyn ^m e) 

specifies the name of the generation data group that is 
being defined. 

LIMIT (lim-it) 

specifies the maximum number, from 1 to 255, of generation 
data sets that can be associated with the generation data 
group to be defined. number can be expressed in decimal 
(n), hexadecimal (X*n f ), or binary (B T n l ) form. 

Abbreviation: LIM 


Optional Parameters 


CAT A LOG C £gjLQanig l / gas^HOUd 3) 

identifies the catalog in which the generation data group 
is to be defined. If the catalog*s volume is physically 
mounted, it is dynamically allocated. The volume must be 
mounted as permanently resident or reserved. For 
information about the order in which a catalog is selected 
when the catalog*s name is not specified, see "Order of 
Catalog Selection for DEFINE" on page 16. 

saAp a m a 

specifies the name of the catalog. 

ga.giiWQ.n_d 

specifies the catalog f s password. If the catalog is 
password protected, you must supply the update- or 
highei—level password. RACF: The update or higher 
RACF authority to the catalog is required. 

Abbreviation: CAT 

EMPTYIN. Q I M P. IY 

specifies what action is to be taken when the maximum 
number of generation data sets for the generation data 
group has been reached and another generation data set is 
to be cataloged. The disposition of the data set's DSCB in 
the volume's VTOC is determined with the SCRATCH I NOSCRATCH 
parameter. 
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EMPTY 

specifies that all the generation data sets are to be 
uncataloged when the maximum is reached (each data 
set's non-VSAM entry is automatically deleted from the 
catalog). 

Abbreviation: EMP 
NOEMPTY 

specifies that only the oldest generation data set is 
to be uncataloged when the maximum is reached. 

Abbreviation: N EMP 

OWNER 

identifies the generation data set's owner. 

Note to TSO users: If the owner is not identified with the 
OWNER parameter, the TSO userid is the default ownerid. 

SCRATCH 1 NOSCRATCH 

specifies whether a generation data set's DSCB is to be 
deleted from the volume's VTOC when the data set is 
uncataloged (that is, when its entry is deleted from the 
catalog automatically, as a result of EMPTY INOEMPTY, or 
specifically, as a result of a user issued DELETE request). 
The user can override the SCRATCH I NOSCRATCH attribute when 
issuing the DELETE command. 

SCRATCH 

specifies that the generation data set's DSCB is to be 
deleted from the volume's VTOC when the generation 
data set is uncataloged. Direct access device space 
management (DADSM) removes the data set's DSCB from 
the VTOC, erases the data set's space on the volume, 
and makes the space available to other system users. 
The generation data set ceases to exist. 

Note: On MSS volumes, even if SCRATCH is specified, 

the data set will not be scratched when it is 
automatically uncataloged. 

Abbreviation: SCR 

NOSCRATCH 

specifies that the generation data set's DSCB is not 
to be removed from the volume's VTOC when the 
generation data set is uncataloged. The data set's 
DSCB in the volume's VTOC is left intact and can be 
used to locate the data set. However, your program 
can process the data set as it processes any other 
non-VSAM data sets—that is, by using a JCL DD 
statement to describe the data set and allocate it. 

Abbreviation: NSCR 

TO(daig)|FOR(day§) 

specifies the retention period for the generation data 
group being defined. 

TOC date ) 

specifies the date, in the form yyddd, where yy is the 
year and ddd is the number (001 through 365) of the 
day through which the generation data group being 
defined is to be kept. 
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FORT davs ) 

specifies the number of days for which the generation 
data group being defined is to be kept. This value 
can be expressed in decimal (n), hexadecimal (X'n 1 ), 
or binary (B , n l ). 

The maximum number that can be specified is 9999. If 
the number specified is 0 through 1830, the generation 
data group is retained for the number of days 
specified; if the number is between 1831 and 9999, the 
generation data group is retained through the year 
1999. If neither TO nor FOR is specified, the 
generation data group can be deleted at any time. 


DEFINE GENERATIONDATAGROUP EXAMPLE 


Define a Generation Data Group and a Generation Data Set within It: Example 1 

In this example, a generation data group is defined in the 
master catalog. Next, a generation data set is defined within 
the generation data group by using JCL statements. 


//DEFGDG1 
//STEP1 
//GDGMOD 
// 

// 

//SYSPRINT DD 
//SYSIN 


JOB 

EXEC PGM=IDCAMS 
DD DSNAME=GDGQ1,DISP=(,KEEP), 

SPACE=CTRK,(0)),UNIT=DISK,VOL=SER=VSER03, 
DCB=(RECFM=FB,BLKSIZE=2Q00,LRECL=10Q) 
SYSOUT=A 
DD X 

DEFINE GENERATIONDATAGROUP - 
(NAMECGDG01) - 


EMPTY ~ 
NOSCRATCH - 
LIMIT(255) ) 


/X 


//DEFGDG2 JOB 

//STEP1 EXEC PGM=IEFBR14 

//GDGDD1 DD DSNAME=GDG01(+1),DISP=(NEW,CATLG), 

// SPACE=(TRK,(10,5)),VOL=SER=VSER03, 

// UNIT=DISK 

//SYSPRINT DD SYS0UT=A 

//SYSIN DD X 


/x 


Job control language statement: 

• GDGMOD DD, which describes the generation data group. When 
the scheduler processes the DD statement, no space is 
allocated to GDG01. 

The model DSCB must exist on the generation data group*s 
catalog volume. 

Because no catalog was specified with a JOBCAT or STEPCAT DD 
statement or with the CATALOG parameter, VSAM assumes all 
entries built for this command sequence are to be cataloged in 
the master catalog. 

The DEFINE GENERATIONDATAGROUP command defines a generation data 
group base catalog entry, GDG01. Its parameters are: 

• NAME, which specifies the name of the generation data group, 
GDG01. Each generation data set in the group will have the 
name GDG01.GxxxxVyy, where "xxxx" is the generation number 
and f, yy” is the version number. 

• EMPTY, which specifies that all data sets in the group are 
to be uncataloged by VSAM when the group reaches the maximum 
number of data sets (as specified by the LIMIT parameter) 
and one more generation data set is added to the group. 
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• NOSCRATCH/ which specifies that when a data set is 
uncataloged, its DSCB is not to be removed from its volume v s 
VTOC. Therefore, even if a data set is uncataloged, its 
records can be accessed when it is allocated to a job step 
with the appropriate JCL DD statement. 

• LIMIT, which specifies that the maximum number of generation 
data sets in the group is 255. The LIMIT parameter is 
required. 

The second job, DEFGDG2, is used to allocate space and catalog a 

generation data set in the newly defined generation data group. 

Job control statement: 

• GDGDD1 DD, which specifies a generation data set in the 
generation data group. 
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VEEinEujmymi 


The DEFINE NONVSAM command defines a catalog entry for a 
non-VSAM data set. The format of this command is: 


DEFINE 


NONVSAM 

C NAME ( eat ry n .m e 3 
DEVICETYPES( devtype [ devtvoe 
VOLUMES( volser E volser ...3) 
EFILESEQUENCENUMBBRSC number C 
[ OWNER t Qmerjd3 3 
CTO[ date 3 I FOR[ davs 3 3 3 


.•3) 


3)3 


CCATALOGC,gjg±Qani.tC/p.a ssw .pr.d3 3 3 


DEFINE can be abbreviated: DEF 


DEFINE NONVSAM PARAMETERS 


Required Parameters 


NONVSAM 

specifies that a non-VSAM data set is to be defined. 
Abbreviation: NVSAM 
name (giitnaiamg 3 

specifies the name of the non-VSAM data set being defined. 
The entryname is the name that appears in the catalog; it 
is the name used in all future references to the data set. 
The entryname must be unique within the catalog in which it 
is defined. 

You identify a generation data set with its generation data 
group name followed by the data set's generation and 
version numbers (GDGname.GxxxxVyy). Relative generation 
numbers (that is, GDGname(+l)) cannot be used with the 
entryname when you use the DEFINE NONVSAM command to 
catalog a generation data set and attach it to a generation 
data group. If the containing catalog is RACF defined, 
then the update or higher RACF authority to the generation 
data group is required. 

DEVICETYPESt devtype E devtvpe ...33 

specifies the device types of the volumes containing the 
non-VSAM data set being defined. If the non-VSAM data set 
resides on different device types, the device types must be 
specified in the same order as the volume serial numbers 
listed in the VOLUMES parameter. 

You can specify a device type for any device that is 
supported by your system. You can specify a generic device 
type (that is, 3380, 3375, 3330). You can only specify a 
device type named by the user (such as SYSDA or TAPE) if 
the name was established in the system device name table 
during system generation. 

CAUTION: When a device type named by the user is specified, 
the device type put in the catalog record is the unique 
device type generated for that unit name in the system 
device name table during SYSGEN. This unique device type 
is a function of the order of that unit name in the Stage 1 
SYSGEN deck. Allocation errors will result if a data set, 
cataloged with a device type named by the user, is referred 
to on a system where SYSGEN generated the unit names 
differently. 

If the catalog is shared between systems, this device type 
may be different if the unit names were not ordered the 
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same in all Stage 1 SYSGEN decks. An I/O GEN may also 
change this device type if the order of unit names in the 
Stage 1 SYSGEN deck is different. 

See the discussion of the SCRATCH|NOSCRATCH option of the 
DELETE command for a restriction on deleting data sets that 
have been defined with a device type named by the user. 

If you expect to change the device type of the system 
residence volume, you can code DEVICETYPESC0000) and this 
field will be resolved at SUPERLOCATE, LOCATE, and DELETE 
time to the device type. This will allow you to use the 
non-VSAM data sets without having to recatalog them to 
point to the new volume. When you code DEVICETYPESC0000) 
you must also code VOLUMESC'XX3CXXX 1 ), or an error will 
result. 

Abbreviation: D EVT 

VOLUMES( volser t volser .. J) 

specifies the volumes to contain the non-VSAM data set. In 
a system with the Mass Storage System, a non-VSAM data set 
can be defined on a mass storage volume. You can specify 
more than one volume serial number if the data set resides 
on many volumes. 

If the data set resides on magnetic tape and more than one 
file belongs to the data set on a single tape volume, you 
must repeat the volume's serial number in order to maintain 
a one to one correspondence between the volume serial 
numbers and the file sequence numbers. 

For example, if your non-VSAM data set is contained in the 
first three files of magnetic tape volume TAPE10, you 
specify: 

DEVICETYPESC3400-6 3400-6 3400-6) - 
VOLUMESCTAPEl0 TAPE10 TAPE10) - 
FILESEQUENCENUMBERSC1 23)- 

If you expect to change the serial number of the system 
residence volumes, you can code VOLUMESC) and this 
field will be resolved at SUPERLOCATE, LOCATE, and DELETE 
time to that number. This will allow you to use the 
non-VSAM data sets without having to recatalog them to 
point to the new volume. 

RACF commands can be used to specify an ERASE attribute in 
a generic or discrete profile for a non-VSAM data set. Use 
of this attribute renders all allocated DASD tracks 
unreadable before space on the volume is made available for 
reallocation. Refer to the appropriate RACF publications 
for information about how to specify and use this facility. 

Abbreviation: VOL 


Optional Parameters 


CATALOG t sa An amg C /pa . s . sw Qr.. d 3 ) 

identifies the catalog in which the non-VSAM data set is to 
be defined. 

For information about the order in which a catalog is 
selected when the catalog's name is not specified, see 
"Order of Catalog Selection for DEFINE" on page 16. 

saAnams 

specifies the name of the catalog in which the entry 
is to be defined. 


E35SfcLQX.d 

specifies the catalog's password. If the catalog is 
password protected, you must supply the update- or 
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higher—level password. RACF: The update or higher 
RACF authority to the catalog is required. 


Abbreviation: CAT 

FILESEQUENCENUMBERS( number £ number ...3) 

specifies the file sequence number of the non-VSAM data set 
being defined. This number indicates the position of the 
file being defined with respect to other files of the tape. 
If the data set spans volumes, the file sequence number on 
each volume must be specified. The numbers must be 
specified in the same order as the volumes in the VOLUMES 
parameter. 

For example, if your non-VSAM data set is contained in the 
first three files of magnetic tape volume TAPE10, you 
specify: 

DEVICETYPESC3400-6 3400-6 3400-6) - 
VOLUMESCTAPE10 TAPE10 TAPE10) - 
FILESEQUENCENUMBERSC1 2 3)- 

DjU&bffE 

can be expressed in decimal Cn), hexadecimal (X f n f ), 
or binary (B f n*) form. 

Abbreviation: FSEQN 

OWNER CoHn e ri- d ) 

identifies the owner of the non-VSAM data set. 

Note to TSO users: If OWNER is not specified, the TSO 
userid is the default ownerid, 

TO( date 1 IFQR( davs ) 

specifies the retention period for the non-VSAM data set 
being defined. The non-VSAM data set is not automatically 
deleted when the expiration date is reached. When you do 
not specify a retention period, the non-VSAM data set can 
be deleted at any time. The expiration date will be placed 
in the catalog, but not in the format-1 DSCB. 

TOt date ) 

specifies the date, in the form yyddd, where yy is the 
year and ddd is the Julian date (001, for January 1, 
through 365, for December 31), through which the 
non-VSAM data set is to be kept before it is allowed 
to be deleted. 

FORCdaYS) 

specifies the number of days for which the non-VSAM 
data set is to be kept before it is allowed to be 
deleted. 

The maximum number that can be specified for days is 
9999. If the number specified is 0 through 1830, the 
retention period is the number of days specified. If 
the number specified is between 1831 and 9999, the 
retention period is through the year 1999. days can 
be expressed in decimal (n), hexadecimal (X*n f ), or 
binary (B'n 1 ) form. 


/jf 
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DEFINE NONVSAN EXAMPLE 


Define a Non-VSAM Data Set: Example 1 

In this example, two existing non-VSAM data sets are defined in 
a catalog, USERCAT4. The DEFINE NONVSAM command cannot be used 
to create a non-VSAM data set because the command does not 
allocate space. 

//DEFNVS JOB 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYS0UT=A 

//SYSIN DD X 

DEFINE NONVSAM - 

(NAMECEXAMPLE.NONVSAM) - 
DEVICETYPES(3380) - 
VOLUMESCVSER02) ) - 
CATAL0GCUSERCAT4/USERMRPW) 

DEFINE NONVSAM - 

(NAMECEXAMPLE.N0NVSAM2) - 
DEVICETYPES(3380) - 
VOLUMESCVSER02) ) - 
CATAL0GCUSERCAT4/USERMRPW) 

/x 

Both DEFINE NONVSAM commands define a non-VSAM data set in 
catalog USERCAT4. The DEFINE NONVSAM commands’ parameters are: 

• NAME, which specifies the name of the non-VSAM data sets, 
EXAMPLE.NONVSAM and EXAMPLE.N0NVSAM2. 

• DEVICETYPES, which specifies the type of device that 
contains the non-VSAM data sets, an IBM 3380-1 Direct Access 
Storage Device. 

• VOLUMES, which specifies the volume that contains the 
non-VSAM data sets, VSER02. 

• CATALOG, which identifies the catalog that is to contain the 
non-VSAM entries, USERCAT4, and its update- or highet—level 
password, USERMRPW. 
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B&EINK... P AG E5 PAQI5 


The DEFINE PAGESPACE command defines an entry for a page space 
data set. The format of this command is: 


DEFINE 


PAGESPACE 


CNAME(g n* r.yn a . ffl fll 
{CYLINDERSC primarv 31 
RECORDS Cp.rjma|^31 
TRACKSCprimary 3 3 
VOLUME( volser 3 
[ATTEMPTS! number 123 3 
[AUTHORIZATION! entrypoint t 
[CODE! code 3 3 
[CONTRQLPW( p^^ M.ar. d 3 3 
[FILE! .ddnamg 3 3 
[MASTERPW( password 3 3 

[ mode L C I/gas^ ond 3 


[QWNERC.gvmeE.ld3 3 
[ READPWC password 3 3 
[ SWAP 1 NOSWAP 3 
[TOC date 31 FORC davs 3 3 
[ UNIQUE |SUBALLOCATION 3 
[UFDATEPWC password 3 3 3 


stringm 


[ CATALOG C gatnams E /jg a ^ s vmild 3 3 3 


DEFINE can be abbreviated: DEF 


DEFINE PAGESPACE PARAMETERS 


Required Parameters 


PAGESPACE 

specifies that a page space is to be defined. 

Abbreviation: PGSPC 
NAME C . ft p t r .y. n3 J ne 3 

specifies the name of the page space being defined. 

CYLINDERSC orimarv 3I 
RECORDS! primary 31 
TRACKS! primary 3 

specifies the amount of space that is to be allocated by 
tracks, cylinders, or number of records. If RECORDS or 
TRACKS is specified, the quantity specified is rounded up 
to the nearest cylinder and the space is allocated in 
cylinders. 

To determine the exact amount of space allocated, list the 
page space ! s catalog entry, using the LISTCAT command. 

If you do not specify the MODEL parameter, you must specify 
one, and only one, of the following parameters: CYLINDERS, 
RECORDS, or TRACKS. 

When you specify UNIQUE, and the page space's data space is 
the first data space on the volume that belongs to a 
recoverable catalog, an additional amount (the equivalent 
of one cylinder) is allocated for the recovery area data 
space. 

EJlil lia jr y 

specifies the amount of space that is to be allocated 
to the page space. After the primary extent is full, 
the page space is full. The page space cannot extend 
onto secondary extents. 
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primary can be expressed in decimal (n), hexadecimal 
(X'n*), or binary (B'n 1 ) form. 

Abbreviations: CYL, REC, and TRK 

VQLUMESf volser 1 

specifies the volume that contains the page space. 

In a system with the Mass Storage System, a page space 
cannot reside on a mass storage volume. 

Unless you specify the MODEL parameter, you must specify 
the VOLUMES parameter. 

The VOLUMES parameter interacts with other DEFINE PAGESPACE 
parameters. You should ensure that the volume(s) you 
specify for the page space are consistent with the page 
space's other attributes: 

• SUBALLOCATION: If suballocation is specified, the 
volume must contain a VSAM data space. 

• CYLINDERS, RECORDS, TRACKS: The volume must contain 
enough unallocated space to satisfy the page space's 
space requirement. 

• FILE: The volume information supplied with the DD 
statement pointed to by FILE must be consistent with 
the information specified for the page space. 

• CATALOG: If the page space is suballocated, the data 
space on the volume must have been defined in the same 
catalog as the page space, and must be owned by the 
catalog. 

Abbreviation: VOL 


Optional Parameters 


CATALOG ( catname t/ password !) 

specifies the name and password of the catalog in which the 
page space is to be defined. 

When the CATALOG parameter identifies a user catalog, you 
must also supply a STEPCAT or JOBCAT DD statement to 
describe and allocate the user catalog. For information 
about the order in which catalogs are selected, see "Order 
of Catalog Selection for DEFINE" on page 16. 

caipame 

specifies the name of the catalog. 

aassfeMLcri 

specifies a password. If the catalog is 
password-protected, you must supply the catalog's 
update- or higher-level password. If no password is 
specified, VSAM may ask the operator or TSO terminal 
user for the correct password. RACF: The update or 
higher RACF authority to the catalog is required. 

Abbreviation: CAT 

ATTEMPTS (jojumhac I Z ) 

specifies the maximum number of times the operator or TSO 
terminal user can try to enter a correct password in 
response to a prompting message. A prompting message is 
issued only when the user has not already supplied the 
appropriate password. When you define a page space, you 
should specify ATTEMPTSCO), so that the operator is not 
prompted and is not allowed to enter a password from the 
console. This parameter only has effect when the entry's 
master password is not null. 
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nmh &r . 

can be any number from 0 to 7. number can be 
expressed in decimal (n), hexadecimal (X'n*), or 
binary (B'n') form. 

Note to TSO users: At a TSO terminal, the logon password 
is checked first before the user is prompted to supply a 
password for the page space. Checking the logon password 
counts as one attempt to obtain a password. If ATTEMPTS is 
not specified, the user has one attempt to supply the page 
space v s password, because the default is 2. 

Abbreviation: ATT 

authorization (, ^n .try.R P i nt I aiding 1) 

specifies that a user-security-verification routine CUSVR) 
is available for additional security verification. When a 
protected page space is accessed and the user supplies a 
correct password other than the page space's master 
password, the USVR receives control. For details on the 
USVR, see £a ±a l g .g..A.dm l . 0is . tc atifig- G uide. 

If a USVR is loaded from an unauthorized library during 
access method services processing, an abnormal termination 
will occur. See "Authorized Program Facility" in Catalog 
Adminisixa i i g oJ^ ^ . 

This parameter only has effect when the entry's master 
password is not null. 

fi. a tcYa. 9i Dt 

specifies the name of the user's-security-verification 
routine. 

siring 

specifies information to be passed on to the USVR when 
it receives control to verify authorization. 

Abbreviation: AUTH 

CODEC code ) 

specifies a code name for the page space. If an attempt is 
made to access a password-protected entry without a 
password, the code name is used in a prompting message; the 
code enables the operator or TSO terminal user to be 
prompted for the password without disclosing the name of 
the entry. If code is not specified and an attempt is made 
to access a page space entry that is password-protected 
without supplying a password, the operator or TSO terminal 
user will be prompted with the name of the entry. 

This parameter only has effect when the cluster f s or 
components master password is not null. 

CONTROLPV^(EasSMUld) 

specifies a control-level password for the page space. 
Because the page space is a system data set, it cannot be 
opened or used by a user's program. 

If a read or update password is the only password specified 
for the page space, it (the highest-level password) 
propagates upward and becomes the password for all higher 
unspecified levels. 

The passwords are cataloged in both the page space entry 
and its data component's entry. The system automatically 
prevents users from accessing page spaces and their data 
components. 

Abbreviation: CT L PW 

FlLE(diinams) 

specifies the name of the DD statement that identifies the 
device and volume to be allocated to the page space. 
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If the page space is unique, and if the FILE parameter is 
not specified and the volume is physically mounted, the 
volume identified with the VOLUME parameter is dynamically 
allocated. The volume must be mounted as permanently 
resident or reserved. 

MASTERPW(HasSHOnd) 

specifies a master password for the page space. The master 
password allows all access method services operations 
against the page space entry. The AUTHORIZATION, CODE, and 
ATTEMPTS parameters have no effect unless the entry has a 
master password associated with it. If MA5TERPW is not 
specified, the highest level password specified becomes the 
password for all higher levels. Because the page space is 
a system data set, it cannot be opened or used by a user's 
program. 

The passwords are cataloged in both the page space entry 
and its data component's entry. The system automatically 
prevents users from accessing page spaces and their data 
components. 

Abbreviation: MRPW 

MODEL ( en l; r y n a me I/£assMQnd3 
[ catname E/ password !1) 

specifies that an existing page space entry is to be used 
as a model for the entry being defined. It is possible to 
use an already defined page space as a model for another 
page space. When one entry is used as a model for another, 
its attributes are copied as the new entry is defined. 

You may use some attributes of the model and override 
others by explicitly specifying them in the definition of 
the page space. If you do not want to add or change any 
attributes, specify only the entry type (page space) of the 
model to be used and the name of the entry to be defined. 

&at ry ,n ame 

specifies the name of the page space entry to be used 
as a model. 

nas swQ r. d 

specifies a password. If the entry to be used as a 
model is password-protected and is cataloged in a 
password-protected catalog, a password is required. 

If the protection attributes are to be copied, 
substitute the master password of either the entry 
being used as a model (following entryname) or the 
catalog in which the entry being used as a model is 
defined (following catname). 

If you specify both passwords, the catalog's password 
is used. If protection attributes are not to be 
copied, any password can be used. RACF: The alter 
RACF authority to the model or catalog is required. 

■satn an n e . 

specifies the name of the catalog in which the entry 
to be used as a model is defined. You identify the 
catalog that contains the model entry for either of 
these cases: 

• You specify the catalog's password instead of the 
model entry's password. 

• The model entry's catalog is not identified with a 
JOBCAT or STEPCAT DD statement, and is not the 
master catalog. 


OWNER CsMOJ&dLd) 

specifies the identification of the owner of the page 
space. 
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READPW C BSS S mLSi ) 

specifies a read-level password for the page space. 

Because the page space is a system data set, it cannot be 
opened or used by a user f s program. 

The passwords are cataloged in both the page space entry 
and its data components entry. The system automatically 
prevents users from accessing page spaces and their data 
components. 

Abbreviation: RDPW 

SWAP 1 M flS MAE 

specifies whether page space will be defined for local 
system queue area (LSQA) pages or for pageable private area 
pages. (Auxiliary storage management separates private 
area address space pages into LSQA pages and pageable 
private area pages.) 

SWAP 

specifies that the page space is a high-speed data set 
used during a swap operation to store and retrieve the 
set of LSQA pages owned by an address space. 

NOSWAP 

indicates that the page space is a conventional page 
space used to record pageable private area pages. 

Abbreviat ion : NSWAP 

TOC date )IFORC davs ) 

specifies the retention period for the page space. 

If neither TO nor FOR is specified, the page space can be 
deleted at any time. 

TOC date ) 

specifies the date, in the form yyddd, where yy is the 
year and ddd is the number (001 through 365) of the 
day through which the cluster being defined is to be 
kept. 

FORC davs ) 

specifies the number of days for which the page space 
is to be kept. The maximum number that can be 
specified is 9999. If the number specified is 0 
through 1830, the page space is retained for the 
number of days specified; if the number is between 
1831 and 9999, the page space is retained through the 
year 1999. 

davs 

can be expressed in decimal (n), hexadecimal 
(X*n f ), or binary (B f n f ) form. 
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UNIQUE |SUBALLOCATION 

specifies whether the page space is allocated an amount of 
space from the volume’s available space (UNIQUE) or from a 
previously defined VSAM data space (SUBALLOCATION). 

UNIQUE 

specifies that the page space is to be allocated a 
VSAM data space of its own. VSAM generates a name for 
the data space and builds a format-1 DSCB in the 
volume’s VTOC to describe it. 

Auxiliary storage management recommends that UNIQUE be 
used for page space data sets. This will cause VSAM 
to allocate a single nonshared data space for the page 
data set. Space from another data space will not be 
used, eliminating one of the possibilities for 
multiple extent data sets that will cause auxiliary 
storage management performance degradation. 

Abbreviation: UNQ 

SUBALLOCATION 

specifies that the name of the data space, not of the 
page space, is to appear in the VTOC. A data space 
must have been defined on the volume on which the page 
space is defined. 

Abbreviation: SUBAL 

UPDATEPWE password ) 

specifies an update-level password for the page space. 
Because the page space is a system data set, it cannot be 
opened or used by a user’s program. 

If a read password is the only password specified for the 
page space (that is, it is the highest-level password), it 
propagates upward and becomes the password for all higher 
levels. If you specify a highei—level password and do not 
specify an update password, the update password is null. 

The passwords are cataloged in both the page space entry 
and its data component’s entry. The system automatically 
prevents users from accessing page spaces and their data 
components. 

Abbreviation: UPDPW 
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DEFINE PAGESPACE 
DEFINE PAGESPACE EXAMPLES 


Define a NOSWAP Page Space: Example 1 




//DEFPGSP1 JOB 

//STEP1 EXEC PGM=IDCAMS 

//VOLUME DD VOL=SER=VSER05,UNIT=DISK,DISP=OLD 

//SYSPRINT DD SYSOUT=A 

//SYSIN DD X 

DEFINE PAGESPACE - 

(NAMECSYSl.PAGE2) - 
CYLINDERSC10) - 
VOLUMESCVSER05) - 
CONTROLPWCPASSWD1) - 
UPDATEPWCPASSWD2) - 
READPWCPASSWD3)) 


/x 


Job control language statement: 

• VOLUME DD/ which describes the volume on which the data 
space is to be defined. 

Because no catalog is explicitly specified with a CATALOG 
parameter or with JOBCAT or STEPCAT DD statements, VSAM assumes 
that the data space and page space are to be defined in the 
master catalog. 

The DEFINE PAGESPACE command defines a page space. This page 
space will have the UNIQUE attribute and hence a new data space 
will be created for its exclusive use. Its parameters are: 

• NAME, which specifies the name of the page space, 

SYS1.PAGE2. 

• CYLINDERS, which specifies that the page space is to occupy 
10 cylinders. The page spaces are never extended. 

• VOLUMES, which specifies that the page space is to reside on 
volume VSER05. 

• CQNTROLPW, which specifies the control password for the page 
space is PASSWD1. 

• UPDATEPW, which specifies the update password for the page 
space is PASSWD2. 

• READPW, which specifies the read password for the page space 
is PASSND3. 

The page space defaults to UNIQUE and NOSWAP. 
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DEFINE PAGESPACE 


Define a SWAP Page Space in a Catalog: Example 2 



//DEFPGSP2 JOB ... 

//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=A 
//SYSIN DD X 

DEFINE PAGESPACE - 

CNAMECSYS1.PAGED - 
CYLINDERSC10) - 
VOLUMESCVSER05) - 
SWAP - 

CONTROLPW(PASSWD1) - 
UPDATEPWCPASSWD2) - 
READPWCPASSWD3)) 

/X 


Because no catalog is explicitly specified with a CATALOG 
parameter or with JOBCAT or STEPCAT DD statements, VSAM assumes 
that the data space and page space are to be defined in the 
master catalog. 


The DEFINE PAGESPACE command defines a page space. Its 
parameters are: 


• NAME, which specifies the name for the page space: 

SYS1.PAGE1. Because the page space is unique, the page 
space's name is put into the DSCB (in the volume's VTOC) 
that describes the space allocated to the page space. 


• CYLINDERS, which specifies that the page space occupies 10 
cylinders and cannot be extended. 


• VOLUMES, which identifies the volume on which the page space 
is to reside. Because no DD statement describes the volume, 
an attempt is made to dynamically allocate the volume. 

Volume VSER05 must be mounted as permanently resident or 
reserved. 

• SWAP, which specifies the page space will be used to store 
local system queue area (LSQA) pages. 

• C0NTR0LPW, which specifies the control password for the page 
space is PASSWD1. 

• UPDATEPW, which specifies the update password for the page 
space is PASSWD2. 

• READPW, which specifies the read password for the page space 
is PASSWD3. 


The page space defaults to UNIQUE. 
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DEFINE PATH 

DEEIH E J PA I H 


The DEFINE PATH command defines a path directly over a base 
cluster or over an alternate index and its related base cluster. 
The format of this command is: 


DEFINE 


PATH 


C NAME t en.tryj3.am^) 

pathentry ( .eplran g me E /pa sste Qr d 3) 

EATTEMPTS( number | g )3 


£ . tr in g 3 3 3 


[CODEC code )I 

[ controlpw(H assnand)3 

EFILEt ddname )3 
EMASTERPWC password )3 
E MODEL (fiO-tcYn3m.fi E /jpassvjojrd 3 
[ catname E/ password ]3)3 
E OWNER C pwneri.d) 3 


ETOC date )I FORC davs )3 
[ UPDATE I NOUPDATEI 
EUPDATEPWCBa§SilQrjd31) 


[ CATALOG C G3±rmm & E / pass w Q .r.d 3 3 3 


DEFINE can be abbreviated: DEF 


DEFINE PATH PARAMETERS 


Required Parameters 


PATH 

specifies that a path is to be defined. 


specifies the path f s name. 

PATHENTRYC en±ry jp am j£E/mssworcj3) 

when the path consists of an alternate index and its base 
clusters, entryname identifies the alternate index entry. 
When the path is opened to process data records, both the 
alternate index and the base cluster are opened. 

When the path consists of a cluster without an alternate 
index, entryname identifies the cluster. You can define 
the path as though it were an alias for the cluster. This 
allows you to specify no-update access to the cluster, so 
that the upgrade set will not be required or updated when 
the cluster is opened (provided the open does not cause 
sharing of a control block structure specifying UPDATE). 

You can also establish protection attributes for the 
alternate name, separate from the protection attributes of 
the cluster. 

Pa ss w o rd 

If the cluster or alternate index entry is 
password-protected, you must supply the entry’s master 
password. When you identify the catalog with the 
CATALOG parameter, you can supply the catalog’s master 
password instead of the entry’s password. RACF: The 
alter RACF authority to the cluster, alternate index 
entry or catalog is required. 

Abbreviation: PENT 
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Optional Parameters 


ATTEMPTStnu m berI2) 

specifies the maximum number of times the operator can try 
to enter a correct password in response to a prompting 
message. 

This parameter only has effect when the path's master 
password is not null. A prompting message is issued only 
when the user has not already supplied the appropriate 
password. 

Dunik.ec 

is an integer from 0 to 7 and can be expressed in 
decimal (n), hexadecimal (X'n 1 ), or binary (B'n 1 ) 
form. 

Note to TSO users: At a TSO terminal/ the logon password 
is checked first, before the user is prompted to supply a 
password for the path. Checking the logon password counts 
as one attempt to obtain a password. If ATTEMPTS is not 
specified, the user has one attempt to supply the path's 
password, because the default is 2. 

Abbreviation: ATT 

AUTHORIZATION i mlryjpjiuiil string3) 

specifies that a usei—security-verification routine (USVR) 
is available for additional security verification. When a 
protected path is accessed and the user supplies a correct 
password other than the clusters master password, the USVR 
receives control. For details on the USVR, see Catalog 
. fi uLde • 

If a USVR is loaded from an unauthorized library during 
access method services processing, an abnormal termination 
will occur. See “Authorized Program Facility” in Catalog 
A.d m ipijgi:rat i .qi l . Qu i d s. 

This parameter only has effect when the path's master 
password is not null. 

.g ntr . ypQ . int 

specifies the name of the USVR. 


specifies information to be passed on to the USVR when 
it receives control to verify authorization. 

Abbreviation: AUTH 

CATALOG (£a±D 3 Hie i /pM SStHQ U i 3 3 

identifies the catalog that contains the entry of the 
cluster or alternate index named in the PATHENTRY 
parameter. For information about the order in which a 
catalog is selected if the catalog's name is not specified, 
see "Order of Catalog Selection for DEFINE" on page 16. 

If the clusters or alternate index f s entry is 
password-protected and its catalog is also 
password-protected, you must specify the master password 
for either the entry or the catalog. 

c a Snaing 

specifies the catalog's name. 

specifies the catalog's master password. RACFs The 
alter RACF authority to the catalog is required. 

If the catalog's volume is physically mounted, it is 
dynamically allocated. The volume must be mounted as 
permanently resident or reserved. 
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Abbreviation; CAT 


CODEC code ) 

specifies a code name for the path. 

If an attempt is made to access a password-protected path 
without first supplying an appropriate password* a 
prompting message is issued to the operators console. The 
prompting message includes the code name, which identifies 
the path without revealing its entryname. 

This parameter only has effect when the path's master 
password is not null. When code is not specified, the 
prompting message identifies the path with its entryname. 

CONTROLPW(Has^/PHd) 

specifies a control password for the path. Control 
interval processing is not permitted through a path; the 
control password will permit read and write operations 
against the base cluster. 

If a read or update password is the only password specified 
for the object, it (the highest-level password) propagates 
upward and becomes the password for all higher unspecified 
levels. 

Abbreviation: CT L PW 
FILECddname) 

specifies the name of a DD statement that identifies the 
recovery volume of the alternate index or cluster named 
with the PATHENTRY parameter. FILE is only used when the 
path is defined in a recoverable catalog. 

The recovery volume is the first volume of the base 
cluster's index component when PATHENTRY names a 
key-sequenced cluster or an alternate index over a 
key-sequenced cluster. 

The recovery volume is the first volume of the base 
cluster's data component when PATHENTRY names an 
entry-sequenced cluster or an alternate index over an 
entry-sequenced cluster. 

When FILE is not specified, an attempt is made to 
dynamically allocate the cluster's recovery volume. The 
volume must be mounted as permanently resident or reserved. 

MASTERPW C password ) 

specifies a master password for the path. The master 
password allows all operations against the path. 

If the master password is not specified, the path's 
highest-level password propagates upward and becomes the 
password for all higher levels, including the master 
password. 

If all passwords are null, ATTEMPTS, AUTHORIZATION, and 
CODE have no effect until the master password is specified. 

Abbreviation; MRPW 

MOD E L ( e n t r Y . Q ^ f n.g [ /p.a^sK o rd 3 
t & 3 ,±nm* c /pa,^wp,rd 3 3) 

identifies an existing path entry that is to be used as a 
model for the path being defined. 

You can use some attributes of the model and override 
others by explicitly specifying them in the definition of 
the path. When you do not want to add or change any 
attributes, you specify only the entry type (PATH), the 
path's name, its alternate index's or cluster's name, and 
the model entry's name. 
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e nt r. yoame 

names the entry to be used as a model. entryname must 
name a path entry. 

passwor d 

specifies a password. If the model entry is 
password-protected and it is cataloged in a 
password-protected catalog, you must supply the read 
Cor higher level) password of either the model entry 
or its catalog. If you specify both passwords, the 
catalog's password is used. RACF: The read or higher 
RACF authority to the model or catalog is required. 

If you are not specifying new protection attributes 
for the path (that is, the model's passwords and 
protection attributes are being copied), you must 
supply the master password of either the model entry 
or its catalog. RACF: The alter RACF authority to the 
model or catalog is required. 

£3 ±P 3ing 

names the model entry's catalog. You must identify 
the catalog that contains the model entry for either 
of these cases: 

• If you specify the catalog's password instead of 
the model entry’s password. 

• If the model entry's catalog is not identified 
with a JOBCAT or STEPCAT DD statement, and is not 
the master catalog. 

If the catalog's volume is physically mounted, it is 
dynamically allocated. The volume must be mounted as 
permanently resident or reserved. For information 
about the order in which a catalog is selected when 
the catalog’s name is not specified, see "Order of 
Catalog Selection for DEFINE” on page 16. 

OWNER (jQWQ.fi rid) 

specifies the identification of the path’s owner. 

Note to TSO users: If the owner is not identified with the 
OWNER parameter, the TSO user's userid becomes the ownerid. 

READPW C password ) 

specifies a read password for the path. The read password 
permits read operations against the base cluster's data 
records. 

Abbreviation: RDPW 
TO(dale)lFORCdayg) 

specifies the retention period for the path. The path is 
not automatically deleted when the expiration date is 
reached. When a retention period is not specified, the 
path can be deleted at any time. 

TOC date ) 

specifies the date, in the form yyddd, where yy is the 
year and ddd is the Julian date (001, for January 1, 
through 365, for December 31), through which the path 
is to be kept before it is allowed to be deleted. 

FORCjdayg) 

specifies the number of days for which the entry is to 
be kept before it is allowed to be deleted. days can 
be expressed in decimal (n), hexadecimal CX’n’), or 
binary (B’n 1 ) form. 

The maximum number that can be specified for days is 
9999. If the number specified is 0 through 1830, the 
retention period is the number of days specified. If 
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the number specified is between 1831 and 9999/ the 
retention period is through the year 1999. 

UEMIEI NOUPDATE 

specifies whether the base cluster f s upgrade set is to be 
allocated when the path is opened for processing. 

The upgrade set is a group of alternate indexes associated 
with the base cluster. The alternate indexes are opened 
whenever the base cluster is opened. 

UPDATE 

specifies that when records in the base cluster are 
modified or deleted/ or when records are added to the 
base cluster/ each alternate index in the base 
clusters upgrade set is modified to reflect the 
change in the clusters data, just as a key-sequenced 
cluster f s index is modified each time the cluster f s 
data changes. 

Abbreviation: UPD 

NOUPDATE 

specifies that/ when opening the path/ the path's base 
cluster is to be allocated and the base clusters 
upgrade set is not to be allocated. 

You can specify the NOUPDATE attribute for the path 
even though the UPGRADE attribute is set for one of 
the base cluster's alternate indexes. 

When a path points to a base cluster that has a large 
upgrade set (that is, many alternate indexes are 
associated with the base cluster)/ and the path is 
defined with the NOUPDATE attribute/ you can open the 
path/ and consequently the base cluster/ and none of 
the alternate indexes will be opened. 

Note: NOUPDATE will be overridden by opening the 

path/ allowing sharing of a control block structure 
that permits UPDATE. 

Abbreviation: NUPD 

UPDATEPW( Password ) 

specifies the update password for the path. The update 
password permits read and write operations against the base 
cluster's data records. 

If a read password is the only password specified for the 
object (that is, it is the highest-level password)/ it 
propagates upward and becomes the password for all higher 
levels. If you specify a highei—level password and do not 
specify an update password/ the update password is null. 

Abbreviation: UPDPW 


134 MVS/XA VSAM Catalog: Access Method Services Reference 



DEFINE PATH 


DEFINE PATH EXANPLE 


Define a Path: Example 1 

In this example/ a path is defined. Previous examples 
illustrate the definition of the path f s alternate index/ 

EXAMPLE.AIX/ and the alternate index f s base cluster/ 

EXAMPLE.KSDS2. The alternate index/ path/ and base cluster are 
defined in the same catalog/ USERRCAT. 

//DEFPATH JOB 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYS0UT=A 

//SYSIN DD X 

DEFINE PATH - 

(NAMECEXAMPLE.PATH) - 
PATHENTRYC EXAMPLE.AIX/AIXMRPW) - 
READPW(PATHRDPW) ) - 
CATALOGC USERRCAT/USERUPPW) 

/x 

The DEFINE PATH command builds a path entry to define the path 
EXAMPLE.PATH. A copy of the path entry is placed in the catalog 
recovery area/ because the path entry is being defined into a 
recoverable catalog. An attempt is made to dynamically allocate 
the catalog recovery area on volume VSER01. The command^ 
parameters ares 

• NAME/ which specifies that the path f s name is EXAMPLE.PATH. 

• PATHENTRY/ which identifies the alternate index/ 

EXAMPLE.AIX/ that the path provides access to. 

• READPH/ which specifies the path f s read password/ PATHRDPW. 

• CATALOG/ which in this example supplies the catalog f s update 
password/ USERUPPW. 
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DEFINE SPACE 

BEFJNL3E ACE 


The DEFINE SPACE command defines a VSAM data space in a VSAM 
catalog. The format of this command is: 


DEFINE 


SPACE 

({CANDIDATE| 

CYLINDERS(finimanyE seconda ry])I 
RECORDSC primary E secondary ]) 
RECORDSIZE(average maximum)I 
TRACKS(pr,imaryC secpndary l 
VOLUMES(volserC ygJ L sa r* *«3) 
EFILEtridpaM)]] 

E CAT A LOG (gatoamfi t /jaa^sHsrd 3 )3 


DEFINE can be abbreviated: DEF 


DEFINE SPACE PARAMETERS 


Required Parameters 


SPACE 

specifies that a data space is to be defined. You can also 
use the DEFINE SPACE command to reserve a volume for VSAM f s 
future use. 

Abbreviation: SPC 

CANDIDATE| 

CYLINDERS(pLOJOacyC secondary ]) 1 

records (primaryc s ec ond ary]) RECORDSlZE(aY£E&ae maxici».m) 1 
TRACKS(pri ma ry i secondary]) 

specifies the volume(s) to be reserved for VSAM's future 
use or specifies the amount of space to be allocated in 
terms of cylinders/ number of records/ or tracks. 

You must specify only one of the following parameters: 
CANDIDATE, CYLINDERS, TRACKS, or RECORDS. Nhen you specify 
RECORDS, you must also specify RECORDSIZE. Nhen you 
specify CYLINDERS or TRACKS, you cannot specify RECORDSIZE. 

CANDIDATE 

specifies that the volumes listed in the VOLUMES 
parameter are reserved for future use by VSAM. An 
ownership indicator is set in a format-4 DSCB in the 
volume f s table of contents (VTOC). The volumes are 
reserved for use by the catalog, but no space is 
allocated (other than the primary CRA allocation if 
the catalog is recoverable). Each volume so reserved 
is called a candidate volume. If CANDIDATE is not 
specified, you must specify one of the following 
parameters: CYLINDERS, TRACKS, or RECORDS. 

If a VSAM data space already exists on the volume, you 
cannot specify CANDIDATE. (You can, however, use the 
ALTER command to identify the volume as a candidate 
volume for a VSAM object other than the volume f s 
catalog.) 

Abbreviation: CAN 
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CYLINDERS ( primary ! g^c.Q.Qdary3) 1 
RECORDS!p rimar y( . ge g ondary 3 ) 

RECORDSIZE! average maximum )I 
TRACKS(pr i macyE secondary3) 

specifies the amount of space to be allocated in terms 
of tracks/ cylinders/ or number of records. 

If RECORDS is specified/ the space required is 
calculated in terms of the number of records/ but the 
space is allocated by tracks. However/ if you specify 
TRACKS or RECORDS and the minimum number of tracks 
exceeds a cylinder/ space is allocated in terms of 
cylinders. 

pri m a r y 

specifies the initial amount of space (primary 
extent) to be allocated to the data space, 
primary can be expressed in decimal (n)/ 
hexadecimal (X , n 1 )/ or binary (B'n 1 ) form. 

.g.g. g ..Q.n d q,r.y 

specifies the amount of space that is to be 
allocated to the data space each time it is 
extended. Once the primary extent is filled/ the 
data space can expand to include a maximum of 15 
secondary extents if you have specified a 
secondary extent amount. secondary can be 
expressed in decimal (n)/ hexadecimal (X f n f )/ or 
binary (B f n f ) form. 

The secondary space allocation is rounded upward 
to the nearest whole cylinder regardless of your 
specification in terms of TRACKS or RECORDS. 
Consequently/ the total amount of space allocated 
to the data space might exceed the predicted 
limit. 

When the data space is the first data space on a 
volume that belongs to a recoverable catalog/ the 
primary amount is increased by one cylinder. 

Abbreviations: CYL, REC, and TRK 

RECORDSIZE(aygragjg maximum) 

specifies the average and maximum lengths/ in bytes/ 
of the records. 

average and maximum can be any integer value between 1 
and 32 761/ expressed in decimal (n)/ hexadecimal 
(X'n*)/ or binary (B , n l ) form. When you specify the 
RECORDS parameter/ you must also specify RECORDSIZE; 
otherwise/ you cannot specify RECORDSIZE. 

Abbreviation : RECSZ 

VOLUMES (y,Q.l.ser E Y,pJLfS £ X«»«3) 

specifies the volumes on which data spaces are to be 
defined or volumes to be reserved as candidate volumes for 
VSAM's future use. If two or more volumes are specified 
and an amount of space is specified (that is, TRACKS/ 
CYLINDERS/ or RECORDS and RECORDSIZE is specified) the 
amount specified for the primary allocation is allocated on 
each volume. The specified volumes must all be of the same 
device type. When the volume already has a data space on 
it/ subsequent data spaces can be defined and must be 
cataloged in the catalog that owns the volume. A data 
space can be defined on a mass storage volume. 

Abbreviation: VOL 
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DEFINE SPACE 
Optional Parameters 


CATALOG (s.a,iaame t /passHojcd 1) 

identifies the catalog in which the data space is to be 
defined. The CATALOG parameter supplies the name and 
passwords when required# of the catalog that contains the 
volume entry that describes the volume on which the data 
space is to be allocated. 

If the DEFINE SPACE command is used to allocate the 
volume's first VSAM data space or to identify the volume as 
a candidate volume# the CATALOG parameter identifies the 
catalog that is to contain the volume's catalog entry and 
is to own the volume. (For more information about VSAM 
volume ownership# see Cat a IQ9 ..A d m i n l ,5t. r a t i.P-.Q-.fc Mi dS• ) 

If the catalog's volume is physically mounted# it is 
dynamically allocated. For information about the order in 
which catalogs are selected# see "Order of Catalog 
Selection for DEFINE" on page 16. 

■gatnama 

specifies the name of the catalog. 

P.a^w prd 

specifies a password. If the catalog is password 
protected# you must supply the update- or highei—level 
password. RACF: The update or higher RACF authority 
to the catalog is required. 

Abbreviation: CAT 

FlLE(ddimnie) 

specifies the name of the DD statement that identifies the 
device type and volumes to be used for space allocation. 

You cannot use concatenated DD statements to describe more 
than one volume. 

If FILE is not specified and the volume is physically 
mounted# the volume(s) identified with the VOLUMES 
parameter is dynamically allocated. Each dynamically 
allocated volume must be mounted as permanently resident or 
reserved. 



ff N - 
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DEFINE SPACE 


DEFINE SPACE EXAMPLE 


Define a Data Space: Example 1 

In this example^ a data space is defined. The data space is to 
be used to allocate space for VSAM clusters that are 
subsequently defined. 


//DEFSPC1 

JOB 

• . • 

//JOBCAT 

DD 

DSN=D27UCAT1/DISP=SHR 

//STEP1 

EXEC 

PGM=IDCAMS 

//SYSPRINT 

DD 

SYSOUT=A 

//SYSIN 

DD 

X 


DEFINE SPACE - 

CCYLINDERSC30 10) - 
VOLUMESCVSER05)) - 
CATALQGCD27UCAT1/USERMRPW) 

/x 

Access method services defines the data space and allocates its 
space on volume VSER05. The data space is cataloged in 
D27UCAT1, because a JOBCAT DD statement is specified. All 
future data spaces and clusters on volume VSER05 must also be 
cataloged in the same catalog. Non-VSAM data sets on the volume 
reside in areas that are not allocated to a VSAM data space. 

The DEFINE SPACE command defines a VSAM data space. Its 
parameters are: 

• CYLINDERS/ which specifies that 30 cylinders are to be 
allocated for the data space. When the data space is 
extended/ it is to be extended in increments of 10 
cylinders. 

• VOLUMES/ which specifies the volume serial number of the 
volume on which the data space is to be defined: VSER05. 

• CATALOG/ which in this example supplies the user catalog f s 
name/ D27UCAT1/ and its master password/ USERMRPW. 
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B£ F I NE - MSE RCA I A I . QP .I M A S T E R, C A TAIIQQ 


The DEFINE USERCATALOGIMASTERCATALOG command defines a VSAM user 
or master catalog. When you use this command* you can specify 
attributes for the catalog as a whole and for the components of 
the catalog. 

The format of this command is: 


DEFINE 


USERCATALOG|MASTERCATALOG 
(NAME(e n try na me) 

{CYLINDERSt primarv E secondary 1)| 

RECORDS tPX. i m a c.Yt secondary ] 11 
tracks C ErimacyI secandany])J 

VOLUMEt volser ) 

[ATTEMPTS( number |£)1 

EAUTHORIZATIONtfig.tryR.QAjn.tI string ])] 

EBUFFERSPACEtstge|5fiI2)] 

ECODEt code )] 

ECONTROLPWt password )] 

E DESTAGEWAIT i MMES I M fiM M I 1 
EFlLEtddnamfi)] 

EMASTERPWf password )] 

E MODEL t e n t r y pa. m e [ /p.a.s.s.wpx.d ] E catname E/ password ] ] ) ] 
EOWNERt ownerid )] 

EREADPWt password )] 

E RECOVERABLE I NO T R E CQV E R A B LE] 

ETOt date )I FORt days )1 
EUPDATEPWt password )] 

EWRITECHECKI NQWRITECHECK J) 

EDATA 

t EBUFFERSPACEt size )] 

E CYLINDERS tpri ma xyE s ,e g .QD d 9Xyl ) I 
RECORDS! primary ! secondary ])I 
TRACKStpr jman yE secondary ])1 
E DESTAGEWAIT|NODESTAGEWAIT] 

ERECORDSIZEt average maximum )] 

E RECOVERABLE|NOTRECOVERABLE] 

EWRITECHECKiNOWRITECHECK])] 

EINDEX 

tECYLINDERSt primary )| 

RECORDS! primary )| 

TRACKS! primary )] 

EDESTAGEWAIT|NODESTAGEWAIT] 

EWRITECHECK|NOWRITECHECK])] 

ECATALOGt mastercatname E/ password ])] 


DEFINE can be abbreviated: DEF 


DEFINE USERCATALOG|MASTERCATALOG PARAMETERS 


Required Parameters 


USERCATALOG|MASTERCATALOG 

specifies that a catalog is to be defined. 

USERCATALOG 

specifies that a user catalog is to be defined. 
USERCATALOG is followed by the parameters specified 
for the catalog as a whole. RACF: The update or 
higher RACF authority to the master catalog is 
required. 

Abbreviation: UCAT 
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MASTERCATALOG 

Processing is identical for the MASTERCATALOG and 
USERCATALOG parameters. When you specify 
MASTERCATALOG, a user catalog is created. You can, 
however, establish a user catalog as a master catalog 
at IPL time. For a description of this procedure, see 
Cg t s lp g-A d mipi^ . 

Abbreviation: MCAT 


NAMEC.QQ.trynams.) 

specifies the name of the catalog being defined. 

CYLINDERSC primary ! secondary ])I 
RECORDS[ primary ! secondary ]3I 
TRACKS [ primar y! se co nd a ry]) 

specifies the amount of space to be allocated in terms of 
cylinders, tracks, or number of records. You can specify 
the amount of space as a parameter of USERCATALOG, as a 
parameter of USERCATALOG and DATA, or as a parameter of 
USERCATALOG, DATA, and INDEX. 


If you specify less than one cylinder of space for a 
recoverable catalog, your DEFINE command will fail. 


For a description of the difference in space allocation 
depending on which parameters you specify, see Catalog 
Administration Guide . This guide also provides information 
about estimating the amount of space to be specified for a 
catalog. 


specify the size of the primary and secondary extents 
to be allocated. Once the primary extent is filled, 
the space can expand to include a maximum of 13 
additional secondary extents if you have specified a 
secondary allocation amount. 

primary and secondary can be expressed in decimal (n), 
hexadecimal (X'n 1 ), or binary dPn*) form. Secondary 
allocation should be specified in case the catalog has 
to be extended. 

Abbreviations: CYL, REC, and TRK 
VOLUMEC vo1ser ) 

specifies the volume that is to contain the catalog. The 
volume cannot be currently owned by any other VSAM catalog. 

The VOLUME parameter interacts with other DEFINE CATALOG 
parameters. You should ensure that the volume you specify 
for the catalog is consistent with the catalog*s other 
attributes: 

• CYLINDERS, RECORDS, TRACKS: The volume contains enough 
unallocated space to satisfy the catalog's primary 
space requirement. (Space on the volume might already 
be allocated to non-VSAM data sets and system data 
sets.) 

• FILE: The volume information supplied with the DD 
statement is consistent with the information specified 
for the catalog and its components, 

A user catalog can be defined on a mass storage volume. 

Abbreviation: VOL 
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ATTEMPTS (number: I Z ) 

specifies the maximum number of times the operator can try 
to enter a correct password in response to a prompting 
message. 

m mh&L 

is an integer from 0 to 7 and can be expressed in 
decimal (n), hexadecimal (X’n 1 ), or binary (B , n f ) 
form. If 0 is specified/ the operator is not prompted 
and is not allowed to enter a password from the 
console. 

Note to TSO users: At a TSO terminal the logon password is 
checked first/ before the user is prompted to supply a 
password for the catalog. Checking the logon password 
counts as one attempt to obtain a password. If ATTEMPTS is 
not specified/ the user has one attempt to supply the 
catalog’s password/ because the default is 2. 

Abbreviation: ATT 

AUTHORIZATIONC l S±riag] ) 

specifies that a user-security~verification routine (USVR) 
is available for additional security verification. When a 
protected catalog is accessed and the user supplies a 
correct password other than the catalog’s master password/ 
the USVR receives control. For information on the 
uset—security-verification routine, see Catalog 
A d ffl i n i .. s .trg.tl.p,D.J?..y..ld^. 

mtr^olnj:. 

specifies the name of the USVR. 

st.niDg 

specifies information to be passed on to the USVR when 
it receives control to verify authorization. 

Abbreviation: AUTH 

BUFFERSPACEC size | 3072 ) 

specifies the minimum space, in bytes, to be provided for 
buffers when using the catalog (one not residing on a 
3380). Decimal values you can specify are 3072, 4096, 

5120, 6144, 7168, and 8192. 

size 

is the amount of space, in bytes, to be provided for 
buffers. Size can be expressed in decimal (n), 
hexadecimal CX’n’), or binary (B’n 1 ) form, but must 
not exceed 16776704. 

Abbreviation: BUFSP 

CATALOG(magl^JLQ.a±Dam ^i 3) 

specifies the name and password of the master catalog. If 
the master catalog is password protected, its update- or 
highei—level password must be provided in this parameter or 
in response to prompting. 

ma^ iLe -nca- t aa me 

is the name of the master catalog that is required 
when a user catalog is being defined. 

specifies the update- or highei—level password of the 
master catalog that is required when a user catalog is 
being defined, if the master catalog is password 
protected. 

Abbreviation: CAT 
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CODE(jeiidg) 

specifies a code name for the catalog being defined. If an 
attempt is made to access a password-protected catalog 
without a password , the code name is used in a prompting 
message; the code enables the operator to be prompted for 
the password without disclosing the name of the catalog. 

If CODE is not specified/ the operator will be prompted 
with the name of the catalog. 

CONTRO LPW ( password ) 

specifies a control password for the catalog being defined. 
The control password permits the same operations as the 
update password. 

If a read or update password is the only password specified 
for the catalog, it (the highest-level password) propagates 
upward and becomes the password for all higher levels. 

When the master password is specified but the control 
password is not specified/ the control password is null. 

Abbreviation: CTLPW 

DESTAGEWAIT | MSBESIASIMMI 

specifies whether a user catalog that is stored on a mass 
storage volume is to be destaged synchronously or 
asynchronously with respect to the program that closes it. 

If the user catalog is not stored on a mass storage volume/ 
the attribute is ineffective until the direct access 
storage volume/ the catalog is stored on is converted to a 
mass storage volume (using the CONVERTV command described 

in 0, 3, /V.S M . a s jlJLIq rag ntAs &gl Re fer^nge 

Iaf, Q .i:m a tA„ g ,n) • 

If one of these parameters is specified for the data 
component of a catalog and the other parameter is specified 
for the index component/ the parameter specified for the 
index component applies to both components/ because the 
sequence set of the index of a catalog is embedded in the 
data. 

DESTAGEWAIT 

indicates that destaging is to be completed before 
control is returned from VSAM to the program that 
issues the CLOSE macro. VSAM can thus notify the 
program whether destaging was successful. 

Abbreviation: DSTGW 

NODESTAGEWAIT 

indicates that notification of unsuccessful destaging 
is to be made only by a message to the operator. 

Abbreviation: NDSTGW 

FILEtddname) 

specifies the name of the DD statement that identifies the 
device and volume to be used for the catalog. The DD 
statement should specify DISP=QLD to prevent premature 
space allocation on the volume. 

If FILE is not specified and the catalog f s volume is 
physically mounted/ the volume identified with the VOLUME 
parameter is dynamically allocated. The volume must be 
mounted as permanently resident or reserved. 

MASTERPWC password ) 

specifies a master password for the catalog being defined. 

A catalog must have a master password in order for VSAM 
data sets cataloged in it to be password-protected. The 
AUTHORIZATION, CODE, and ATTEMPTS parameters have no effect 
unless the catalog has a master password associated with 
it. The master password allows all operations; it is 
required to open the catalog as a data set. 
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If a master password is not specified for the catalog/ the 
catalog’s highest-level password propagates upward and 
becomes the password for all higher levels/ including the 
master password. The master password is null when no other y 

passwords are specified. 

Abbreviation: MRPW 

MODEL t£n±rynam.e i /R3 SSWp .rd 3 i sat n amfi E /MLSSM Pr -d 3 3) 

specifies that an existing master or user catalog is to be 
used as a model for the user catalog being defined. 

It is possible to use an already defined master or user 
catalog as a model for another user catalog. 

When one entry is used as a model for another/ its 
attributes are copied as the new entry is defined. You may 
use some attributes of the model and override others by 
explicitly specifying them in the definition of the user 
catalog. 

If a model is used/ you must specify certain parameters 
even though no attributes are to be changed or added. The 
name of the user catalog to be defined and volume and space 
information must always be specified as parameters of 
USERCATALOG. 

s n tcxm ms 

specifies the name of the master or user catalog to be 
used as a model. 

jBaasMgrri 

specifies a password. If the catalog to be used as a 
model is password-protected/ a password is required. 

If you specify both passwords (that is, the password /\ 

following entryname and the password following 

catname)/ the password following catname is used for vy 

authorization. 

If the protection attributes are to be copied/ enter 
the master password of the catalog being used as a 
model. RACFs The alter RACF authority to the catalog 
is required. If passwords are not to be copied/ any 
password except the master can be used. 

gainams 

specifies the name of the catalog to be used as a 
model. This parameter is required if the model 
catalog is neither the master catalog nor a catalog 
identified by a JOBCAT or STEPCAT DD statement. 

OWNER C ,q w ngrJL ri 1 

specifies the identification of the owner of the catalog 
being defined. 

READPW ( password ) 

specifies a read password for the catalog being defined. 

The read password permits the user to list the catalog's 
entries. (Passwords and protection attributes are listed 
only when the master-level password is supplied.) 

Abbreviation: RDPW 

RECOVERABLEIMflIRE£ fl VEBA& LE 

specifies whether a catalog recovery space is to be created 
on each volume owned by the catalog. 

RECOVERABLE 

specifies that a catalog recovery space is to be t 4 

created. U 

On the catalog's volume/ the catalog recovery space is 
allocated from the catalog's data space. On 
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subsequent volumes owned by the catalog, the catalog 
recovery space is allocated from the first data space 
defined on the volume. 

Primary allocation for a CRA is one cylinder. Once a 
primary extent is filled, the CRA can expand to 
include a maximum of 15 additional extents. 

Allocation for each secondary extent is one cylinder. 

The number of records a CRA can contain varies with 
the device type (for example, for a 3330 with 20 
control intervals per track, each extent will 
accommodate approximately 370 records). 

Abbreviation: RVBL 

NOTRECOVERABLE 

specifies that no catalog recovery space is to be 
created. 

Abbreviation: NRVBL 
TOC date )IFOR( davs ) 

specifies the retention period for the catalog being 
defined. If no value is coded, the catalog can be deleted 
whenever it is empty. 

T0Cjdll±£) 

specifies the date, in the form yyddd, where yy is the 
year and ddd is the number (001 through 365) of the 
day through which the catalog being defined is to be 
kept. 

FORC davs ) 

specifies the number of days for which the catalog 
being defined is to be kept. 

The maximum number that can be specified is 9999. If 
the number specified is 0 through 1830, the catalog is 
retained for the number of days specified; if the 
number is between 1831 and 9999, the catalog is 
retained through the year 1999. 

davs 

can be expressed in decimal (n), hexadecimal 
(X'n*), or binary (B'n 1 ) form. 

UPDATEPWCfiaJSSHfind) 

specifies an update password for the catalog being defined. 
The update password permits entries to be added to the 
catalog being defined. The catalog must be update 
password-protected in order to prevent unauthorized users 
from cataloging data sets. 

If a read password is the only password specified for the 
catalog (that is, it is the highest-level password), it 
propagates upward and becomes the password for all higher 
levels. If you specify a highei—level password and do not 
specify an update or read password, the update password is 
null. 

When you anticipate using the catalog to contain many 
non-VSAM entries, you should consider allowing the 
catalog's update password to be null (that is, to specify a 
master password but not an update password). A null update 
password allows you to alter and delete non-VSAM entries 
without having to supply the catalog's password. 

Abbreviation: UPDPW 

WRITECHECK I NQWRITECHECK 

specifies whether the catalog is to be checked by a direct 
access device operation called write check when a record is 
written to the device. 
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WRITECHECK 

specifies that a record is to be written and then 
read/ without data transfer. 

Abbreviation: WCK 

NOWRITECHECK 

specifies that the catalog is not to be checked by a 
write check when a record is written to the device. 

Abbreviation: NWCK 


(■ 


DATA AND INDEX COMPONENTS OF USERCATALOG 

Attributes can be specified separately for the catalog's data 
and index components. The DATA and INDEX parameters are listed 
at the beginning of this section. These parameters are 
described in detail as parameters of the catalog as a whole. 
Restrictions are noted with each parameter's description. 
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DEFINE USERCATALOG EXAMPLES 


Defining a VSAM User Catalog, Having Calculated Its Space Requirements: Example 1 

In this example, a user catalog is defined. The user catalog's 
data space is not available to contain other VSAM objects. The 
catalog is to be large enough to contain information about: 

• 100 key-sequenced clusters (that is, indexed VSAM data sets) 

• 10 entry-sequenced clusters (that is, sequential nonindexed 
VSAM data sets) 

• 5 key-sequenced clusters with alternate indexes to be 
upgraded 

• 5 entry-sequenced clusters with alternate indexes to be 
upgraded 

• 10 alternate indexes 

• 10 paths 

• 200 aliases 

• 10 generation data sets 

• 1000 non-VSAM data sets. 

• 5 volumes (the number to be controlled by the catalog). 

Each volume is a 3330 volume and contains 20 data spaces. 

To determine how much space, in records and tracks, is required 
for the primary allocation of a catalog still to be defined in 
your system, see C ata l jag^A, ^ The number of 

records for the primary allocation of the catalog in this 
example is shown in the completed worksheet in Figure 3 on 
page 148. 

When you define the catalog's space parameters, use the 
following format: 

DEFINE USERCATALOG - 

(TRACKS(prim seen) ... ) 


where: 

• prim = the minimum amount of space for the catalog data 

space's primary allocation. In this example, all the data 
space is assigned to the catalog itself. The calculated 
value of prim should be rounded upward to the next whole 
number of tracks that is an even multiple of the catalog 
allocation unit for the device type being used (For the size 
of an allocation unit, see .Ca Guide . ) 

Because the catalog resides on a 3330-1 volume, the value of 
prim is: 

prim = .09N + 3 = 152.4 = = 153 tracks 
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Variable Quantities 


Basic requirement * 10 records 
A = number of key-sequenced clusters 
A 1 s number of key-sequenced clusters with alternate 
indexes to be upgraded 
B = number of entry-sequenced clusters 
B 1 = number of entry-sequenced clusters with alternate 
indexes to be upgraded 
C = number of relative-record clusters 
D = number of alternate indexes 
E = number of path entries 
F s number of nonVSAM data set entries 
G * number of generation data group entries 
H = number of alias entries 
I s number of page spaces 
J = number of volumes, depending on device type, 
owned by the catalog: 

J 1 = number of 2305 volumes 
J 2 = number of 2314/2319 volumes 
J 2 = number of 3330 and 3340/3344 volumes 
J* = number of 3330 Model 11 and 3350 volumes 
K = for each key-sequenced cluster and alternate index 
(KSDS) with space on more than two volumes, add 
"\" for each additional group of one to five 
volumes: 

K* = number of KSDSs with 3 to 7 volumes 
K 2 = number of KSDSs with 8 to 12 volumes 
K 2 = number of KSDSs with 13 to 17 volumes 
L = for each entry-sequenced cluster and relative-record 
cluster (LSDS) with space on more than five 
volumes, add "I” for each additional group of one 
to eight volumes: 

L 1 = number of ESDSs with 6 to I 3 volumes 
L 2 = number of ESDSs with 14 to 21 volumes 
M * for each group of four data spaces on a volume, 
add “I” 

N * number of entry records required for the catalog's 
data component (total of above) 


Formulas 



Figure 3. Completed Worksheet for Determining a Catalog's Space 
Requirements 


• seen = the minimum amount of space for each secondary extent 
of the catalog's data space. 

The number of tracks required for the catalog's primary 
extent is at least 153. This figure is an even multiple of 
an allocation unit for a 3330 device (3); therefore, no 
further rounding is necessary. If VSAM extends the catalog, 
it should extend it in increments of 18 tracks. 

//DEFCAT2 JOB 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYSQUT=A 

//SYSIN DD X 

DEFINE USERCATALOGC - 
NAMECUSERCAT3) - 
VOLUMECVSER04) - 

TRACKSC153 18) ) r 

/x | 


148 MVS/XA VSAM Catalog: Access Method Services Reference 






















DEFINE USERCATALOG|MASTERCATALOG 


The DEFINE USERCATALOG command defines a user catalog. Its 

parameters are: 

• NAME, which specifies the name of the catalog, USERCAT3. 

• VOLUME, which specifies that the catalog is to reside on the 
volume whose serial number is VSER04. 

• TRACKS, which specifies that the catalog T s data space is to 
be 153 tracks. When the user catalog is extended, VSAM 
extends it in increments of 18 tracks. 

• Values and attributes that apply by default to the catalog 
are BUFFERSPACE = 3072 bytes, ATTEMPTS = 2, NGWRITECHECK, 
NQDESTAGEWAIT, and NOTRECOVERABLE. 


Define a User Catalog Leaving Available Suballocatable Space: Example 2 

In this example, a user catalog is defined. The catalog will 

actually occupy only a portion of the space defined, leaving the 

remainder of the space available for the suballocation of other 

VSAM data sets. 

//DEFCAT3 JOB 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYS0UT=A 

//SYSIN DD X 

DEFINE USERCATALOGC - 

NAMECD27UCAT1) - 
MASTERPWC USERMRPW) - 
UPDATEPWCUSERUPPW) - 
FGRC365) - 
CYLINDERSC10 1)) - 
VOLUMECVSER02) ) - 
DATAC - 

CYLINDERSC3 1) - 
INDEXC - 

CYLINDERS(l) ) - 
CATALOGCAMAST1/MASTUPW1) 

/x 

The DEFINE USERCATALOG command defines a user catalog, D27UCAT1. 

Its parameters are: 

• NAME, which names the user catalog, D27UCAT1. 

• MASTERPW and UPDATEPW, which specify master and update 
passwords for the catalog: USERMRPW and USERUPPW. 

• FOR, which specifies that the user catalog is to be retained 
for 365 days. 

• CYLINDERS, which specifies that 10 cylinders are to be 
allocated for the user catalog's data space. When the user 
catalog's data space is extended, it is to be extended in 
increments of 1 cylinder. 

• VOLUME, which specifies that the catalog is to reside on 
volume VSER02. Volume VSER02 will be dynamically allocated. 

• DATA and INDEX, which specify that VSAM is to allocate 4 
cylinders for the catalog itself. VSAM determines the 
proportion of space that is allocated to the catalog's data 
and index components. The remainder of the catalog's data 
space (6 cylinders) is available to contain VSAM objects 
that reside in a nonunique data space. If the catalog's 
data component is extended, it is to be extended in 
increments of 1 cylinder. The catalog's index component is 
never extended. 

• CATALOG, which specifies that the user catalog connector 
entry is to be defined in the master catalog, AMAST1. 
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CATALOG provides the catalog's update passwords MASTUPW1, so 
that the operator is not prompted to provide it. /< 

• Values and attributes that apply by default to the catalog V y 

are BUFFERSPACE = 3072 bytes, ATTEMPTS = 2, NOTRECOVERABLE, 
NQWRITECHECK, and NQDESTAGEWAIT. 


Define a User Catalog Using the MODEL Parameter: Example 3 

In this example, the user catalog defined previously, D27UCAT1, 
is used as a model for the user catalog being defined, D27UCAT2. 


//DEFCAT4 

JOB 

... 

//STEP1 

EXEC 

PGM=IDCAMS 

//STEPCAT 

DD 

DSNAME=D27UCAT1,DISP=SHR 

//SYSPRINT 

DD 

SYS0UT=A 

//SYSIN 

DD 

X 


DEFINE USERCATALOGC - 

NAMECD27UCAT2) - 
MASTERPW(USERMRPW) - 
UPDATEPW(USERUPPW) - 
CYLINDERSC15 5) - 
VOLUMECVSER03) - 
MODEL C D27UCAT1/MRPWD27 - 
D27UCAT1/MRPWD27) ) - 
CATAL0GCAMAST1/MASTUPW1) 


Job control language statement: 

• STEPCAT DD, which makes a catalog available for this job 
step: D27UCAT1. 

The DEFINE USERCATALOG command defines catalog D27UCAT2. Its 

parameters are: 

• NAME, which names the catalog, D27UCAT2. 

• MASTERPW and UPDATEPW, which specify master and update 
passwords for the catalog: USERMRPW and USERUPPW. 

• CYLINDERS, which specifies that 15 cylinders are to be 
allocated for the catalog's data space. The catalog itself 
will reside within this data space. When the catalog's data 
space is extended, it is to be extended in increments of 5 
cylinders. 

• VOLUME, which specifies that the catalog is to reside on 
volume VSER03. Volume VSER03 will be dynamically allocated. 

• MODEL, which identifies D27UCAT1 as the catalog to use as a 
model for D27UCAT2. The attributes and specifications of 
D27UCAT1 that are not otherwise specified with the above 
parameters are used to define the attributes and 
specifications of D27UCAT2. The master catalog, AMAST1, 
contains a user catalog connector entry which points to 
D27UCAT1. This is why D27UCAT1 is specified as MODEL'S 
catname subparameter. Values and attributes that apply to 
D27UCAT2 as a result of using D27UCAT1 as a model are FOR = 
365 days, CYLINDERS = 3 (primary) and 1 (secondary) for the 
data component and 1 (primary) for the index component, 
BUFFERSPACE = 3072 bytes, ATTEMPTS = 2, NOWRITECHECK, and 
NQDESTAGEWAIT. 

• CATALOG, which specifies that the user catalog connector is 
to be defined in the AMAST1 catalog. The update password of 
AMAST1 is MASTUPW1. 
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Define a VSAM Recoverable User Catalog: Example 4 

In this example^ a recoverable user catalog is defined. 


//DEFCAT5 

JOB 

• • • 

//STEP1 

EXEC 

PGM=IDCAMS 

//V0L1 

DD 

VQL = SER=VSER01,UNIT=DISK,DISP^OLD 

//SYSPRINT 

DD 

SYSOUT=A 

//SYSIN 

DD 

X 


DEFINE USERCATALOGC - 

NAME(USERRCAT) - 
MASTERPWC USERMRPW) - 
UPDATEPWC USERUPPW) - 
TOC99365) - 
ATTEMPTSC3) - 
CODECBEQUIET) - 
RECOVERABLE - 
TRACKSC100) - 
FILE(VQLl) - 
VOLUMECVSER01) ) - 
DATAC - 

RECORDSC500 100)) - 
CATALOGCAMAST1/MASTUPW1) 


Job control language statement* 

• V0L1 DD, which describes the volume on which the catalog is 
to be defined. 

The DEFINE USERCATALOG command defines a user catalog/ USERRCAT. 

Its parameters are* 

• NAME/ which names the user catalog/ USERRCAT. 

• MASTERPW and UPDATEPW/ which specify master and update 
passwords for the catalog: USERMRPW and USERUPPW. 

• TO, which specifies that the user catalog is to be retained 
until 31 December 1999. 

• ATTEMPTS/ which specifies that the operator may be prompted 
for the correct password up to three times. 

• CODE/ which specifies that the catalog is identified, in the 
prompting message to the operator, with the name "BEQUIET". 

• RECOVERABLE, which specifies that the catalog f s volumes 
contain catalog recovery areas and the LISTCRA, EXPQRTRA, 
IMPORTRA, and RESETCAT commands can be used to restore 
entries in the catalog. 

• TRACKS, which specifies that 100 tracks are to be allocated 
for the user catalog f s data space. No secondary allocation 
is specified. If additional VSAM space is required on the 
volume, it can be explicitly defined using the DEFINE SPACE 
command. 

• FILE, which points to the V0L1 DD statement. The V0L1 DD 
statement directs the operating system scheduler to mount 
and allocate the volume on which the user catalog is to 
reside. In this example, the volume is not dynamically 
allocated. 

• VOLUME, which specifies that the user catalog is to reside 
on volume VSER01. 
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• DATA, which specifies that VSAM is to allocate space to 
accommodate 500 records for the user catalog. VSAM 
determines the total amount of space that is allocated to 
the catalog’s data and index components. The remainder of 
the catalog’s data space is available to contain the catalog 
recoverable area (CRA) and other VSAM objects that reside in 
a nonunique data space. If the catalog’s data component is 
extended, it is extended in increments to accommodate 100 
records. 

You may wish to estimate the amount of space which VSAM will 
actually allocate to the catalog in order to: 

- Ensure that the total amount of space specified via 
TRACKS is large enough. 

- Determine how much suballocatable space will be 
available. 

Because the catalog resides on a 3330-1, the total amount of 
space will be: 

aN + b = (0.1116 x 500) + 4 = 59.8 = 60 tracks 


• CATALOG, which specifies that the user catalog connector is 
to be defined in the AMAST1 catalog. The update password of 
AMAST1 is MASTUPH1. 

• Values and attributes that apply by default to the catalog 
are BUFFERSPACE = 3072 bytes, NOWRITECHECK, and 
NODESTAGEWAIT. 
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The DELETE command deletes catalogs* VSAM data sets* and 
non-VSAM data sets. The format of this command is: 


DELETE 


C ant ry n .amflC^ p a s a w and3[ gn .tr, y namsE/BassM Q crf3 ...3) 

[ALIAS | 

ALTERNATEINDEXI 
CLUSTER| 

GENERATIONDATAGROUP| 

NONVSAM| 

PAGESPACE| 

PATH | 

SPACE| 

USERCATALOG 
[ERASE|NOERASE3 
[FILEt ddname )1 
[ FORCE|NO£OR£E 3 
[ PURGE ItjO PURGE 3 
[ SCRATCH I NOSCRATCH] 


[ CATALOG i /pas.sw.Q. r d 3 ] ] 


DELETE can be abbreviated: DEL 


DELETE PARAMETERS 


Required Parameters 


tg n Ar y iiamfit/ p,aM .hLQ.rd3E e n tr .Yn ^mg t/ pa . s ^ ,w .s>r. d 3 * * * 3) 

names the entries to be deleted. If more than one entry is 
to be deleted* the list of entrynames must be enclosed in 
parentheses. 

This parameter must be the first parameter following 
DELETE. 

giLtrypamg 

is the name of the entry to be deleted or the volume 
serial number of the volume that contains a data space 
to be deleted. A generic name may be coded in order 
to delete multiple entries with one entryname. (For 
example* GENERIC. x. BAKER is a generic name where f, x ,f 
is any 1- to 8-character simple name.) 

If you are deleting a member of a non-VSAM partitioned 
data set* the entryname must be specified in the 
format: pdsname(membername). If you are deleting a 
non-VSAM data set that was defined by coding 
DEVICETYPES(OQ00) and VOLUMESC 1 xxxxxx 1 )* then DELETE 
only uncatalogs the data set. It does not scratch it 
from the SYSRES volume. 

Pass wa c d 

specifies a password for a password-protected entry. 
Passwords may be specified for each entryname* or the 
catalog's password may be specified through the 
CATALOG parameter for the catalog that contains the 
entries to be deleted. Only certain types of catalog 
entries can be password protected* as specified below. 

To delete: 

• Alias* specify the catalog's update- or 

higher-level password. RACF: The RACF alter 
authority to the entry to which the alias is 
related is required. 
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• Alternate index, specify the entry's master 
password, or the catalog's master password. RACF: 
The RACF alter authority to the alternate index or 
to the catalog is required. 

• Cluster, specify the entry f s master password, or 
the catalog f s master password. RACF: The RACF 
alter authority to the cluster or to the catalog 
is required. 

• Data space, specify the catalog's update- or 
highei—level password. RACF: The RACF alter 
authority to the catalog is required. 

• Generation data group, specify the catalog's 
update- or highei—level password. RACF: The RACF 
alter authority to the GDG base or to the catalog 
is required. 

• Non-VSAM entry, specify the catalog's update- or 
highei—level password. RACF: The RACF alter 
authority to the non-VSAM data set or to the 
catalog is required. 

• Page space, specify the entry's master password, 
or the catalog's master password. RACF: The RACF 
alter authority to the page space or to the 
catalog is required. 

• Path, specify the entry's master password, or the 
catalog's master password. RACF: The RACF alter 
authority to the path or to the catalog is 
required. 

• User catalog, specify the entry's master password 
with the entryname so that access method services 
does not issue a prompting message to the operator 
or TSO terminal user. RACF: The RACF alter 
authority to the user catalog is required. 


Optional Parameters 


ALIASIALTERNATEINDEXI CLUSTERI 

GENERATXONDATAGROUP|NONVSAM|PAGESPACE| 

PATH I SPACE IUSERCATALOG 

specifies the type of object or entry to be deleted. SPACE 
is required to delete a data space, and USERCATALOG is 
required to delete a catalog. 

ALIAS 

specifies that the entry to be deleted is an alias 
entry. 

ALTERNATEINDEX 

specifies that the object to be deleted is an 
alternate index and its data and index entries. 

When a path entry is associated with the alternate 
index, the path entry is also deleted. 

When the alternate index has the attribute that is 
still to be upgraded and it is the only such alternate 
index associated with the base cluster, the base 
cluster's upgrade set entry is also deleted. 

Abbreviations AIX 

CLUSTER 

specifies that the object to be deleted is a cluster, 
its associated data and index entries, and any related 
paths and alternate indexes. 
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If the cluster is defined in a recoverable catalog, 
DELETE requires the catalog recovery volume for the 
cluster to be mounted. If the CRA volume is not 
available, then any volume with the required CRA 
volume serial number satifies DELETE’s requirements. 

Abbreviation: CL 

GENERATIONDATAGROUP 

specifies that the entry to be deleted is a generation 
data group entry. To delete a generation data group 
that is not empty, you must specify the FORCE 
parameter. 

Abbreviation: GDG 

NONVSAM 

specifies that the entry to be deleted is a non-VSAM 
data set entry. 

If the non-VSAM data set has aliases, all of its alias 
entries are deleted. 

If the non-VSAM data set is partitioned, you can 
delete one of its members by specifying 
pdsnameCmembername). 

RACF commands can be used to specify an ERASE 
attribute in a generic or discrete profile for a 
non-VSAM data set. Use of this attribute renders all 
allocated DASD tracks unreadable before space on the 
volume is made available for reallocation. Refer to 
the appropriate RACF publications for information 
about how to specify and use this facility. 

Abbreviation: NVSAM 

PAGESPACE 

specifies that an inactive page space is to be 
deleted. A page space is identified as "active" 
during the operator’s IPL procedure. 

Abbreviation: PGSPC 


PATH 

specifies that a path entry is to be deleted. No 
entries associated with the path are deleted. 


SPACE 

specifies that all empty VSAM data spaces on a volume 
are to be deleted. This parameter is required when 
you want to delete the volume’s empty data spaces. 

To delete a data space that is not empty, you must 
specify both the SPACE parameter and the FORCE 
parameter. 

If all data spaces on a volume have been deleted and 
the volume is not a candidate or catalog volume, its 
volume entry is also deleted. 

Note: When a volume entry in the catalog is deleted, 

VSAM's ownership of the volume is relinquished. When 
the catalog that owns the volume is recoverable, the 
data space that contains the volume’s recovery area is 
not deleted unless all other data spaces on the volume 
have been deleted. CRAs must be deleted in a separate 
command. 

Abbreviation: SPC 
USERCATALOG 

specifies that the object to be deleted is a user 
catalog. 
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The catalog connector entry in the master catalog is 
deleted. If the user catalog has aliases/ all the 
catalog's alias entries in the master catalog are 
deleted. 

To delete a user catalog when it is empty (that is, it 
contains only its self-describing entries and its 
volume's volume entry)/ you must specify USERCATALOG. 
To delete a user catalog that is not empty/ you must 
specify both USERCATALOG and FORCE. 

Note: The JOBCAT/STEPCAT is ignored for this command. 
EXPORT DISCONNECT must be used to delete a user 
catalog entry from a user catalog. A master catalog 
for another system is considered to be a user catalog 
by the processing system. 

Abbreviation: UCAT 

CAT alog (sat,nam e C /mssnard 3) 

specifies the name of the catalog that contains the entries 
to be deleted. For information about the order in which 
catalogs are searched/ see "Order of Catalog Search for 
DELETE" on page 17. 

Note: This parameter cannot be used to delete a user 

catalog. 


identifies the catalog that contains the entry to be 
deleted. 

password 

specifies the password of the catalog that contains 
the entries to be deleted. 

If entries to be deleted are password-protected and 
the catalog is also password-protected/ a password 
must be supplied either through CATALOG or with the 
name of each entry to be deleted. The password that 
must be specified for each entry type is given under 
the description of the entryname parameter. 

If a password is supplied through the CATALOG 
parameter/ it takes precedence over any password 
supplied with the entryname parameter and is used for 
all entries to be deleted. 

A JOBCAT or STEPCAT DD statement may be needed when 
dynamic allocation is required/ because the name of 
the catalog cannot be passed to dynamic allocation via 
the CATALOG parameter. 

Abbreviation: CAT 

ERASE|NOERASE 

specifies whether the data component of a cluster or 
alternate index to be deleted is to be erased/ that is, 
overwritten with binary zeros. 

This parameter will override whatever was coded when the 
cluster or alternate index was defined or last altered. 

This parameter should be specified only when a cluster or 
an alternate index entry is to be deleted. When you 
specify ERASE/ you must identify the catalog of the entry 
that is still to be deleted with a JOBCAT or STEPCAT DD 
statement unless: 


The entry is in the master catalog/ or 

The first qualifier in the entry's qualified name is 
the catalog's name or alias. 



(f '\ 
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ERASE 

specifies that the data component is to be overwritten 
with binary zeros when the cluster or alternate index 
is deleted. If ERASE is specified/ the volume that 
contains the data component must be mounted. 

Abbreviat ion 2 ERAS 

NOERASE 

specifies that the data component is not to be 
overwritten with binary zeros when the cluster or 
alternate index is deleted. 

Abbreviat ion : N ERAS 

FlLECddnamfi) 

specifies the name of the DD statement that identifies: 

• The volume that contains a unique data set to be 
deleted. 

• The partitioned data set from which a member (or 
members) is to be deleted. 

• The data set to be deleted if ERASE is specified. 

• The volume that contains the data space to be deleted. 

• The catalog recovery volume(s) when the entry being 
deleted is in a recoverable catalog. If the volumes 
are of a different device type, concatenated DD 
statements must be used. (The catalog recovery volume 
is the volume whose recovery space contains a copy of 
the entry being deleted.) (For more details on catalog 
recovery volume mounting requirements, see Catalog 

Admin i st r a.ti. p n .J S m i de .) 

• The volume(s) owned by the catalog when you delete a 
catalog using the FORCE option. 

If you do not specify FILE and VSAM requires access to a 
volume or volumes during the delete processing, VSAM will 
attempt to dynamically allocate the volumes. When ERASE is 
specified and FILE is not specified, the entryname will 
attempt to be dynamically allocated. Dynamic allocation 
requires that the volume(s) must be mounted as permanently 
resident or reserved. 

When more than one volume is to be identified (for example, 
a multivolume data set), FILE identifies the DD statement 
that specifies all volumes. If in any of the above cases 
the volumes are of a different device type, concatenated DD 
statements must be used. All volumes that contain 
associations to a cluster being deleted must also be 
included on the ddcard referenced by the FILE parameter. 

When deleting multivolume non-VSAM data sets with the 
SCRATCH option, DELETE SCRATCH processing will require 
access to each volume in the entry*s catalog record before 
the scratch can be issued. This will require either all 
volumes to be mounted, online, and allocable to the job, or 
the use of the FILE parameter specifying a DD statement 
allocating at least one mountable unit (not permanently 
resident or reserved). Deferred mount must be specified on 
the DD statement so that allocation will flag the UCB to 
allow demount/mount requests to be issued for the unit as 
required during delete processing. If access to the 
volumes cannot be provided, then DELETE NOSCRATCH can be 
used to uncatalog the non-VSAM data set and the user will 
assume the responsibility of scratching the format-1 DSCBs 
from all the volumes. 
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FORCE 1 MBEQJS£E 

specifies whether objects that are not empty should be ^ 

deleted. ( 

-j 

FORCE 

allows you to delete data spaces, generation data 

groups, and user catalogs without first ensuring that 

these objects are empty. 

If you delete a data space using FORCE: 

• All VSAM data spaces on the volume(s) are 
scratched from the VTOC. VSAM's ownership of the 
volume(s) is given up. 

• Before the data spaces are scratched, VSAM 
verifies that no VSAM clusters on the volume are 
open. The clusters remain cataloged, but their 
entries are marked unusable. Subsequently, you 
can delete the cluster from the catalog. 

• You cannot specify FORCE to delete the space on a 
volume that contains the VSAM master catalog or a 
user catalog. 

• You must supply the master password of the catalog 
that contains the volume's entry. 

If you delete a generation data group using FORCE: 

• The GDG entry is deleted even though it might 
point to non-VSAM entries in the catalog. 

• Each non-VSAM data set entry pointed to by the GDG 
base entry is deleted before the GDG base entry is 
deleted. However, the non-VSAM data set f s space 
and contents on the volume are undisturbed. The 
data set can be located with its DSCB in the 
volume's VTOC. 

If you delete a user catalog using FORCE: 

• The catalog is deleted even though it contains 
catalog entries for objects that have not been 
deleted. All cataloged objects are automatically 
deleted, but the contents of each cluster and 
alternate index are not erased. 

• Before data spaces are deleted, VSAM verifies that 
no VSAM clusters on the volume are open. All data 
spaces are deleted from each volume owned by the 
catalog. The volumes are then available to be 
used by the system or to be assigned to other VSAM 
catalogs. 

• VSAM clusters and alternate indexes, even though 
they might reside in unique data spaces, cannot be 
located, because the data space's DSCB is 
scratched when the catalog is deleted. 

• Non-VSAM data set entries in the catalog are 
deleted, but the non-VSAM data set's space on the 
volume is undisturbed. The non-VSAM data set can 
be located with its DSCB in the volume's VTOC. 

• You must supply the master password of the catalog 
being deleted. 

Abbreviation: FRC 
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NOFORCE 

causes the DELETE command to terminate when you 
request the deletion of a data space generation data 
group/ or catalog that is not empty. 

Abbreviation: NFRC 

PURGE| liflPJIRQE 

specifies whether the entry is to be deleted regardless of 
the retention period specified. This parameter cannot be 
used if a data space entry is to be deleted. 

PURGE 

specifies that the entry is to be deleted even if the 
retention period/ specified in the TO or FOR 
parameter# has not expired. 

Abbreviation: PRG 

NOPURGE 

specifies that the entry is not to be deleted if the 
retention period has not expired. 

Abbreviation: NPRG 

SCMIEH | NOSCRATCH 

specifies whether a data set is to be removed from the VTOC 
of the volume on which it resides. This parameter can only 
be specified for a cluster# an alternate index# a page 
space# or a non-VSAM data set. 

SCRATCH 

specifies that a non-VSAM data set or a data space is 
to be removed from the VTOC of the volume on which it 
resides. 

When SCRATCH is specified for a cluster# alternate 
index# or page space defined with the UNIQUE 
attribute# the entry for the data set is removed from 
the VTOC. For a cluster# alternate index# or page 
space defined with the SUBALLOCATE attribute# the 
entry is deleted from the catalog and thus removed 
from the data space. The entry is not removed from 
the VTOC. 

When you specify SCRATCH# you must identify the 
catalog of the entry to be deleted with a JOBCAT or 
STEPCAT DD statement# unless the entry is in the 
master catalog# or the first qualifier in the entry’s 
qualified name is the catalog’s name or alias# or the 
FILE parameter is specified. 

To remove the format-1 DSCB from the VTOC you should 
use the SCRATCH function of the OS/VS IEHPROGM 
utility. 

Note: If you specify SCRATCH when deleting a non-VSAM 

data set that was defined with a device type named by 
the user# the DELETE will fail. 

Abbreviation: SCR 

NOSCRATCH 

specifies that the entry is to be deleted from the 
catalog only# without mounting the volume that 
contains the object defined by the entry. 

You should specify NOSCRATCH for the followings 

• If the format-1 DSCB of a non-VSAM data set has 
already been scratched from the VTOC. 
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• If you are deleting a non-VSAM data set that was 
defined with a device type named by the user (for 
example^ SYSDA). 

NOSCRATCH cannot be specified for VSAM clusters/ 
alternate indexes/ or page spaces in VSAM recoverable 
catalogs. 

For more detailed information about the use of DELETE 
NOSCRATCH/ see "VSAM Catalog Cleanup" in Catalog 
A d m i ni^ixaii on, .Quids» 

Abbreviation: NSCR 
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DELETE EXAMPLES 


Deleting a Non-VSAM Data Set's Entry: Example 1 

In this example, a non-VSAM data set’s entry is deleted. The 
SCRATCH parameter is the default. A FILE parameter and its 
associated DD statement are provided to allocate the data set's 
volume. In this example, dynamic allocation is not used to 
provide catalog or volume allocation. 

//DELET4 JOB 

//STEP1 EXEC PGM=IDCAMS 

//DD1 DD V0L=SER=VSER02,UNIT=DISK,DISP=GLD, 

// DSNAME=EXAMPLE.NONVSAM 
//SYSPRINT DD SYS0UT=A 

//SYSIN DD X 

DELETE - 

EXAMPLE.NONVSAM - 
FILE (DD1) - 
PURGE - 

CATAL0GCUSERCAT4/USERUPPW) 

/x 

The DELETE command deletes the non-VSAM data set 
EXAMPLE.NONVSAM. Its parameters are: 

• EXAMPLE.NONVSAM, which is the entryname of the object to be 
deleted. 


• FILE, which specifies the ddname of a DD statement that 

describes the non-VSAM data set’s volume and causes it to be 
mounted. When the data set is deleted, its DSCB entry in 
the volume’s VTOC is removed. 


PURGE, which specifies that the non-VSAM data set's 
retention period or date is to be ignored. 


• CATALOG, which identifies the catalog that contains the 
entries, USERCAT4, and its update password, USERUPPW. 
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Deleting a Key-Sequenced VSAM Cluster in a Catalog: Example 2 

In this example, a key-sequenced cluster is deleted. Alternate 
indexes and paths related to the key-sequenced cluster are \ 

deleted automatically by access method services. Access method 
services dynamically allocates the key-sequenced data set so 
that the data can be overwritten (as specified by the ERASE 
option). 


//DELETl 

JOB 

• • • 

//JOBCAT 

DD 

DSN=D27UCAT2,DISP=SHR 

//STEP1 

EXEC 

PGM=IDCAMS 

//SYSPRINT 

DD 

SYSOUT =A 

//SYSIN 

DD 

X 

DELETE - 



D40.EXAMPLE.KSDS1 - 
PURGE - 
ERASE - 

CATAL0GCD27UCAT2/USERMRPW) 

/X 

Job control language statements 

• JOBCAT DD, which makes a catalog available for the job: 
D27UCAT2. 

The DELETE command deletes the key-sequenced VSAM cluster from 

the D27UCAT2 catalog. Its parameters ares 

• D40.EXAMPLE.KSDS1, which is the entryname of the object 
being deleted. D40.EXAMPLE.KSD51 is a key-sequenced VSAM 
cluster. 

• PURGE, which specifies that the cluster is to be deleted 
regardless of its retention period or date. 

• ERASE, which specifies that the cluster f s data component is 
to be overwritten with binary zeros, regardless of a NOERASE 
attribute that might have been specified when the cluster 
was defined or altered. 

• CATALOG, which identifies the catalog that contains the 
cluster’s entries, D27UCAT2. The catalog’s master password 
is required, unless the entry’s master password is specified 
with the entryname. 
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Deleting an Entry-Sequenced VSAM Cluster in a VSAM Catalog and All Empty Data Spaces 
On a Volume: Example 3 

In this example, an entry-sequenced VSAM cluster is deleted. 
Alternate indexes and paths related to the entry-sequenced 
cluster are automatically deleted by access method services. 
Next, all empty VSAM data spaces on volume VSER03 are deleted, 
and the volume's volume entry is deleted. 

//DELET2 JOB ... 

//JOBCAT DD DSNAME=D27UCAT2,DISP=OLD 

//STEP1 EXEC PGM=IDCAMS 

//DD2 DD VOL=SER=VSER03,UNIT=DISK,DISP=OLD 

//SYSPRINT DD SYS0UT=A 
//SYSIN DD X 
DELETE - 

EXAMPLE.ESDS2/ESD2MRPW - 
PURGE - 
CLUSTER 
DELETE - 

VSER03 - 
SPACE - 
FILE (DD2) 

/X 

Job control language statement: 

• JOBCAT DD, which makes a catalog available for the job: 
D27UCAT2. 

The first DELETE command deletes the only VSAM cluster on volume 
VSER03. The DELETE command's parameters are: 

• EXAMPLE.ESDS2, which is the entryname of the cluster to be 
deleted, and ESD2MRPW, which is the cluster's master 
password. 

• PURGE, which specifies that the cluster is to be deleted 
regardless of its retention period or date. Alternate 
indexes and paths related to the entry-sequenced cluster are 
also deleted, regardless of their retention periods or 
dates. 

• CLUSTER, which specifies that the entryname EXAMPLE.ESDS2 
identifies a VSAM cluster entry. 

The second DELETE command causes VSAM to examine each data space 
cataloged in the volume's entry. If the data space is empty, it 
is deleted. VSAM deletes the volume entry when there are no 
data spaces cataloged in it, and when there are no data sets 
identified that specify the volume as a candidate volume. VSAM 
also updates the volume's VTOC to reflect the deleted data 
spaces. The DD2 DD statement ensures that volume VSER03 is 
mounted when its data spaces are deleted. 

In this example, JCL has been used instead of allowing access 
method services to dynamically allocate the volume. If the 
volume were mounted as permanently resident or reserved, access 
method services could dynamically allocate the volume without 
the need of JCL or the FILE parameter. The DELETE command's 
parameters are: 

• VSER03, which identifies the volume that contains empty VSAM 
data spaces. 

• SPACE, which specifies that the entryname identifies a 
volume entry. When a volume's data spaces are to be 
deleted, the SPACE parameter is required. 

• FILE, which specifies the ddname of a DD statement that 
describes the VSAM volume and causes it to be mounted. 
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Deleting Two Key-Sequenced Clusters in a Catalog: Example 4 

In this example, two key-sequenced clusters# D40.MYDATA and 
ENTRY, are deleted from a catalog. This example illustrates how 
more than one cataloged object is deleted with a single DELETE 
command, 

//DELET3 JOB 

//JOBCAT DD DSNAME=USERCAT3,DISP=SHR 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYSGUT=A 

//SYSIN DD X 

DELETE - 

CD40.MYDATA - 
ENTRY) - 
PURGE - 
CLUSTER 
/X 

Job control language statement* 

• JOBCAT DD, which makes the catalog USERCAT3 available for 
the job. 

The DELETE command deletes the key-sequenced clusters D40.MYDATA 
and ENTRY. The high-level qualifier of the object D40.MYDATA 
causes the catalog D27UCAT1 to be searched, because it is 
assumed that D40 is an alias of the catalog D27UCAT1. The 
object ENTRY is found in the catalog USERCAT3, which is made 
available to the job through the JOBCAT DD statement. Both 
entries will be dynamically allocated so that their respective 
catalog recovery areas can be updated. The DELETE command's 
parameters are: 

• D40.MYDATA and ENTRY, which identify the objects to be 
deleted. D40.MYDATA and ENTRY are the entrynames of two 
key-sequenced clusters. It is assumed that neither cluster 
is password-protected at this time. If either cluster is 
password-protected, the operator is prompted to supply the 
cluster's master password. 

• PURGE, which specifies that the cluster is to be deleted 
regardless of its retention period or date. 

• CLUSTER, which specifies that D40.MYDATA and ENTRY identify 
cluster catalog records. 


Deleting Nonempty VSAM Data Spaces on a Volume for a VSAM Catalog: Example 5 

In this example, all of the data spaces on volume VSER05 are 
deleted, whether or not they are empty. All VSAM data spaces on 
the volume are scratched from the VTOC and the ownership of the 
volume is surrendered by the catalog, AMASTCAT. Any clusters or 
alternate indexes contained within the data spaces on volume 
VSER05 are marked unusable in the catalog. Because all VSAM 
data spaces on the volume are deleted, the volume's catalog 
entry is also deleted. 

//DELET5 JOB 

//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=A 
//SYSIN DD * 

DELETE - 

VSER05 - 
SPACE - 
FORCE - 

CATALOGCAMASTCAT/USERUPPW) 

/x 
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The DELETE command f s parameters ares 

• VSERG5, which identifies the volume with its serial number. 
Because the volume’s VTOC must be updated, access method 
services will dynamically allocate the volume. 

• SPACE, which specifies that a volume entry is to be modified 
or deleted. When a volume's data space is to be deleted, 
the SPACE parameter is required. 

• FORCE, which specifies that all VSAM data spaces on the 
volume are to be deleted, whether or not they are empty, and 
that volume ownership is to be released. 

• CATALOG, which identifies the catalog that owns the volume, 
AMASTCAT. The catalog's update- or highei—level password is 
required. 


Deleting a User Catalog: Example 6 

In this example, a user catalog is deleted. A user catalog can 
be deleted when it is empty—that is, when there are no objects 
except the catalog's volume cataloged in it. If the catalog is 
not empty, it cannot be deleted unless the FORCE parameter is 
specified. 

//DELET6 JOB 

//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=A 
//SYSIN DD x 
DELETE - 

D27UCAT1/USERMRPW - 
PURGE ~ 

USERCATALOG 

/x 

The DELETE command deletes the catalog. If a VSAM catalog is 
deleted, the volume that contained the catalog is now available 
for ownership by another VSAM catalog. The DELETE command also 
deletes the catalog's user catalog connector entry in the master 
catalog. The DELETE command's parameters are: 

• D27UCAT1, the name of the user catalog. The catalog's 
update (or higher level) password is required. 

• PURGE, which specifies that the user catalog's retention 
period or date is to be ignored. If PURGE is not specified 
and the catalog's retention period has not yet expired, it 
will not be deleted. 

• USERCATALOG, which identifies D27UCAT1 as a user catalog. 


Deleting an Alias Entry in a Catalog: Example 7 

In this example, an alias entry, EXAMPLE.N0NVSAM1, is removed 
from catalog USERCAT4. 

//DELET7 JOB 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYS0UT=A 

//SYSIN DD X 

DELETE - 

EXAMPLE.N0NVSAM1 - 
ALIAS - 

CATAL0GCUSERCAT4/USERMRPW) 


The DELETE command removes an alias entry from catalog USERCAT4. 
Its parameters are: 

• EXAMPLE.N0NVSAM1, the entryname of the object to be deleted. 
EXAMPLE.N0NVSAM1 identifies an alias entry. 
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• ALIAS/ which specifies the type of entry to be deleted. 

VSAM verifies that EXAMPLE.N0NVSAM1 is an alias entry, then 
deletes it. If EXAMPLE.N0NVSAM1 identified another entry by 
mistake, VSAM would not delete the entry, but would note the 
discrepancy with a message to the programmer. 

• CATALOG, which identifies the catalog that contains the 
entry, USERCAT4, and its master password, USERMRPW. 


Deleting Generically Named Entries in a Catalog: Example 8 

In this example, each catalog entry with the name 
"GENERIC.X.BAKER” is deleted, where "*" is any 1- to 8-character 
simple name. The name "GENERIC.x.BAKER" is a generic name, and 
this example shows how all catalog entries with the same generic 
name are deleted. 

//DELET8 JOB ... 

//JOBCAT DD DSNAME=USERCAT4,DISP=0LD 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYS0UT=A 

//SYSIN DD X 

DELETE - 

GENERIC.X.BAKER - 
PURGE - 

CATAL0GCUSERCAT4/USERMRPW) 

/x 

Job control language statement: 

• JOBCAT DD, which makes a catalog available for this job: 
USERCAT4. 

The DELETE command removes all entries (and their associated 
entries) with the generic name "GENERIC. X. BAKER" from catalog 
USERCAT4. Its parameters are: 

• GENERIC.x.BAKER, a generic name, identifies all catalog 
entries with the name GENERIC.X.BAKER. 

• PURGE, which specifies that each entry is to be purged 
regardless of the retention period or date specified when it 
was defined. 

• CATALOG, which identifies the catalog that contains the 
entries, USERCAT4, and its master password, USERMRPW. 


List a Generation Data Group's Entries, Then Delete the Group and Its Data Sets in a 
Catalog: Example 9 

In this example, a generation data group, GDG01, and its 
associated (generation data set) entries are listed. Next, the 
only generation data set in the group is deleted. Finally, the 
generation data group base catalog entry is deleted. 

//DELET9 JOB 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SY$0UT=A 

//SYSIN DD X 

LISTCAT - 

ENTRIES(GDGQl) - 
ALL 
DELETE - 

GDG01.G0001V00 - 
PURGE 
DELETE - 

GDG01 - 

GENERATIONDATAGROUP - 
PURGE 
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Because no catalog was specified in a CATALOG parameter or with 
a JOBCAT or STEPCAT DD statement, VSAM assumes all entries 
required for this command sequence are in the master catalog. 

The LISTCAT command lists the generation data group GDG01 and 
its associated generation data set entries. Its parameters are: 

• ENTRIES, which specifies that the entry GDG01 is to be 
listed. Because the entry GDG01 is a generation data group 
entry, its associated generation data set's (non-VSAM) 
entries are also listed. In addition, if one of the 
generation data sets has aliases, the alias entries 
associated with the generation data set's entry are listed. 

• ALL, which specifies that all fields are to be listed. 

The first DELETE command removes the non-VSAM data set entry for 
the only generation data set in the generation data group: 

GDG01.G0001V00. Its parameters are: 

• GDG01.GQ0G1V00, the entryname of the object being deleted. 
GDG01.G0001V00 identifies the only generation data set in 
the generation data group GDG01. 

• PURGE, which specifies that the generation data set's 
retention period or date is to be ignored. 

The second DELETE command removes the catalog entry of the 
generation data group base from the catalog. Its parameters 
are: 

• GDG01, the entryname of the object being deleted. GDG01 
identifies the generation data group base entry. 

• GENERATIONDATAGROUP, which specifies the type of entry to be 
deleted. VSAM verifies that GDG01 is a generation data 
group entry, then deletes it. If GDG01 incorrectly 
specified another type of entry, VSAM would not delete the 
entry, but would note the discrepancy with a message to the 
programmer. 

• PURGE, which specifies that the generation data group's 
retention period or date is to be ignored. 


Deleting a Member of a Partitioned (Non-VSAM) Data Set in a Catalog: Example 10 

In this example, the MEM1 member of partitioned data set 
EXAMPLE.N0NVSAM2 is deleted. Next, the non-VSAM data set itself 
is deleted. 

//DELET10 JOB 

//JOBCAT DD DSNAME=USERCAT4,DISP=SHR 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYS0UT=A 

//SYSIN DD X 

DELETE - 

EXAMPLE.N0NVSAM2CMEM1) - 
CATAL0GCUSERCAT4/USERMRPW) 

DELETE - 

EXAMPLE.N0NVSAM2 - 
PURGE - 

CATAL0GCUSERCAT4/USERMRPW) 


Job control language statement: 

• JOBCAT DD, which makes a catalog available for this job: 
USERCAT4. 
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The first DELETE command deletes one of the members of a 
partitioned data set, EXAMPLE.NQNVSAM2CMEM1), from the user 
catalog, USERCAT4. Its parameters are: 

• EXAMPLE.N0NVSAM2CMEM1), which is the entryname of one of the 
members of the partitioned (non-VSAM) data set, 

EXAMPLE.N0NVSAM2. The entryname identifies the object to be 
deleted. 

• CATALOG, which identifies the catalog that contains the 
entry, USERCAT4, and its master password, USERMRPW. 

The second DELETE command deletes all remaining members, as well 
as the data set itself, of the partitioned non-VSAM data set 
EXAMPLE.N0NVSAM2, Its parameters are: 

• EXAMPLE.N0NVSAM2, which is the entryname of the object to be 
deleted. 

• PURGE, which specifies that the non-VSAM data set’s 
retention period or date is to be ignored. If PURGE had not 
been specified and the non-VSAM data set’s retention period 
has not yet expired, VSAM would not delete its entry. 

• CATALOG, which identifies the catalog that contains the 
entry, USERCAT4, and its master password, USERMRPW. 

In the second part of this example, the DSCB entry in the 
volume’s VTOC is removed. Dynamic allocation is used to 
allocate the data set’s volume. 


Deleting a Page Space: Example 11 

In this example, page space SYS1.PAGE2 is deleted. 

//DELET11 JOB 
//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT^A 

//SYSIN DD X 

DELETE - 

SYS1.PAGE2/MASTMPW1 - 
PURGE - 
PAGESPACE 
/x 

The DELETE command removes the page space entry, SYS1.PAGE2, 

from the master catalog. Its parameters are: 

• SYS1.PAGE2, the entryname of the object to be deleted. 
SYS1.PAGE2 identifies a page space entry. The catalog’s 
update- or highei—level password is also required. 

• PURGE, which specifies that the page space entry is to be 
deleted regardless of the retention period or date specified 
when it was defined. 

• PAGESPACE, which specifies the type of entry to be deleted. 
VSAM verifies that SYS1.PAGE2 is a page space entry, then 
deletes it. If SYS1.PAGE2 incorrectly identified another 
type of entry, VSAM would not delete it, but would send an 
error message to the programmer. 
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EXAMINE 


EXMIHE 


The EXAMINE command analyzes and reports on the structural 
consistency of the index component and/or data component of a 
key-sequenced data set (KSDS) cluster. The format of the EXAMINE 
command is: 


EXAMINE 

NAMEf clusternameC/password 3 ) 


[INDEXTES1 

[[NOINDEXTEST] 


CDATATEST 

NODATATEST3 


£ERRORLIMIT(value)3 


EXAMINE PARAMETERS 


Required Parameters 


NAME (£lM5.tg.cnamfi £ / Bassa&cd 3 > 

specifies which user cluster is to be analyzed for 
structural consistency by EXAMINE. EXAMINE expects the 
user to have specified a particular key-sequenced data set 
by its cluster name. The appropriate cluster component is 
then selected dynamically during program execution. When 
analyzing a VSAM catalog, use a STEPCAT DD statement to 
point to that catalog and apply a VERIFY DATASET command 
before using the EXAMINE command. A STEPCAT DD statement is 
not required for the master catalog. 

pj..y[sie_rname. 

specifies the identification of the key-sequenced data 
set cluster to be analyzed. 

p aa stttt o l 

specifies, optionally, the master password associated 
with a catalog or the control password for a data set. 


Optional Parameters 


im b e x ie s i i noindextest 

specifies whether or not EXAMINE is to perform tests 
associated with the index component of the cluster. 
INDEXTEST is the default. 

INDEXTEST 

performs tests upon the index component of a 
key-sequenced data set cluster. 


Abbreviation; ITEST 
NOINDEXTEST 

does not perform any testing upon the index component 
of a key-sequenced data set cluster. 


Abbreviation: NOITEST 
DATATESTI NODATATEST 

specifies whether or not EXAMINE is to perform tests 
associated with the data component of the cluster. 
NODATATEST is the default. 
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DATATEST 

performs tests upon the data component of a 
key-sequenced data set cluster. NOINDEXTEST and 
DATATEST are specified when only a DATATEST is 
desired. 


Abbreviation: DTEST 
NODATATEST 

does not perform any testing upon the the data 
component of a key-sequenced data set cluster. 


Abbreviation: NODTEST 
ERRORLIMIT(value) 

specifies a numeric limit (value) to the number of errors 
for which detailed EXAMINE error messages are to be printed 
during program execution. ERRORLIMIT is designed to 
prevent runaway message output. The default value for 
ERRORLIMIT is 2147483647 errors, but you can specify any 
number between 0 and 2147483647. Note that testing 
continues even though the error limit is reached. 


Abbreviation: ELIMIT 


EXAMINE EXAMPLES 


Examine Both Components of a Key-Sequenced Data Set: Example 1 

This example shows how to get a list of data set structural 
errors that can be used to support problem resolution. 

//EXAMEX2 JOB 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYSGUT=A 

//SYSIN DD X 

EXAMINE - 

NAME(KSDSOl) - 
INDEXTEST - 
DATATEST 


Use the EXAMINE command to analyze both components of a 
key-sequenced data set. Its parameters are: 

• NAME, which specifies the cluster name only. The data set 
has no control level password protection. 

• INDEXTEST, which causes the index component to be examined. 

• DATATEST, which causes the data component to be examined. 

• The default for ERRORLIMIT (it was not specified) allows 
detailed error messages to be printed. 
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EXAMINE 


Examine the Data Component of a VSAM User Catalog: Example 2 

This example shows how to determine whether your VSAM catalog 
has structural errors. 

//EXAMEX3 JOB 

//STEP1 EXEC PGM=IDCAMS 

//STEPCAT DD DSN=VCATQ1.VCAT/ DISP=SHR 

//SYSPRINT DD SYS0UT=A 

//SYSIN DD X 

VERIFY DATASET(VCATOl.VCAT) 

EXAMINE - 

NAMECVCAT01.VCAT) - 
NOINDEXTEST - 
DATATEST - 
ERRQRLIMIT(1000) 


Use the EXAMINE command to analyze the data component of a VSAM 

catalog. Its parameters are: 

• NAME/ which specifies the catalog name. The catalog must be 
connected to the master catalog. 

• NOINDEXTEST/ which specifies that the index component is not 
to be examined. 

• DATATEST/ which causes the data component to be examined. 

• ERRORLIMIT(IOOO)/ which restricts the printing of detailed 
error messages to 1000 errors. 


( 


Note that the STEPCAT DD statement and the VERIFY DATASET 
command are required when you use EXAMINE against a VSAM user 
catalog. 
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EXPORT DISCONNECT 

E X PQRI_J? I S CQ.MN EC I 


The EXPORT DISCONNECT command disconnects a user catalog. The ( 

format of this command is: 


EXPORT 


u^j^cajtnajiig i /j ms smrj i 3 

DISCONNECT 


EXPORT DISCONNECT PARAMETERS 


Required Parameters 


userca tname I/ passwo rd 3 

names the user catalog to be disconnected. This parameter 
must be the first parameter following EXPORT. 

When you are disconnecting a user catalog, you must supply 
the update- or highei—level password of the master catalog. 
RACF* The update or higher RACF authority for the master 
catalog is required. 

DISCONNECT 

specifies that a user catalog is to be disconnected. The 
connector entry for the user catalog is deleted from the 
master catalog. Also, the user catalog f s alias entries are 
deleted from the master catalog. 

If EXPORT is coded to remove a user catalog connector 
entry, DISCONNECT is a required parameter. The volume that 
contains a VSAM user catalog can be physically moved to the 
system to which the catalog will be connected. 

A JOBCAT/STEPCAT can be used to delete a user catalog 
connector entry from a user catalog. Any alias entries 
will also be deleted. In this case, the password should be 
the master password of the user catalog specified in the 
JOBCAT/STEPCAT. 

Note: To make a user catalog available in other systems 

and in the original system, code the IMPORT CONNECT command 
to connect the user catalog to each system to which it is 
to be available, but do not EXPORT DISCONNECT the user 
catalog. 

Abbreviation: DCON 


A f 
% 
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EXPORT DISCONNECT 


Export Disconnect of a User Catalog: Example 1 

In this example, the user catalog D27UCAT1 is exported and 
disconnected from the system. Its cataloged objects are no 
longer available to users of the system. 

//EXP0RT3 JOB 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYSGUT=A 

//SYSIN DD X 

EXPORT - 

D27UCAT1/MASTMPW1 - 
DISCONNECT 
/X 

The EXPORT command removes the user catalog connector entry for 
D27UCAT1 from the master catalog. The catalog becomes 
unavailable to system users until the system programmer 
reconnects it to the system using an IMPORT CONNECT command. 

The EXPORT command's parameters are* 

• D27UCAT1, which identifies the object to be disconnected. 
When a user catalog is disconnected, the master catalog's 
master password is required. 

• DISCONNECT, which identifies the object as a user catalog. 
When a user catalog's connector entry is to be deleted, 
DISCONNECT is required. 
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EXP-Qfil 


The EXPORT command exports a VSAM cluster or an alternate index. 
The format of this command is* 


EXPORT 



{OUTFILEfddnams) | OUTDATASET(fintaOUUUl n 


[ERASE|NOERASE1 


IlNFlLECddnams)! 


CINHIBITSOURCE 

tmmmnmmcEi 


tINHIBITTARGET 

NOINHIBITTARGET] 


[PURGEIMfiEURSE] 




EXPORT can be abbreviated: EXP 


EXPORT PARAMETERS 


Required Parameters 


six t c ma m g E 3 

names the cluster or alternate index to be exported. This 
parameter must be the first parameter following EXPORT. 

If you are exporting: 

• A cluster or alternate index, you must supply the 
object f s master password. RACF: The alter RACF 
authority to the cluster or alternate index is 
required. 

• A cluster or alternate index with any 
password-protected paths defined over them, you 
must supply the master password of the catalog 
containing the objects in order to export the 
protection attributes of all the paths. RACF: 

The alter RACF authority to the catalog is 
required. 

OUTFI le ) 1 outdataset ( mirxname. ) 

specifies the name of the DD statement or the data set that 
is to receive the data being exported. 

OUTFILE(ddnamg) 

specifies the name of the DD statement of the target 
data set. 

Only the block size for the DCB parameter should be 
specified in the DD statement. The default for block 
size for EXPORT is 2048. Block size may be specified 
in the DD statement to override this default and 
improve performance. 

Abbreviation: OFILE 

outdataset C e niryna m e) 

specifies the name of the target data set. If 
OUTDATASET is specified, an attempt is made to 
dynamically allocate the target data set. The 
characteristics of the target data set are described 
in "For a Target Data Set" on page 10. 

Abbreviation: ODS 
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EXPORT 





Optional Parameters 


ERASE|NOERASE 

specifies whether the data component of the cluster or 
alternate index to be exported is to be erased (that is, 
overwritten with binary zeros). This parameter overrides 
whatever was specified when the object was defined or last 
altered. 

This parameter can be specified only if the object is to be 
permanently exported (that is, deleted from the original 
system). 

ERASE 

specifies that the data component is to be overwritten 
with binary zeros when the cluster or alternate index 
is deleted. If ERASE is specified, the volume that 
contains the data component must be mounted. 

Abbreviation: ERAS 

NOERASE 

specifies that the data component is not to be 
overwritten with binary zeros when the cluster or 
alternate index is deleted. 

Abbreviation: NERAS 

INFILE Cddoamg) 

specifies the name of the DD statement that identifies the 
cluster or alternate index to be exported. If the cluster 
or alternate index has been defined with a maximum logical 
record length greater than 32760 bytes, EXPORT processing 
terminates with an error message. 

In addition to the DD statement for INFILE, you must 
identify the entry's catalog with a JOBCAT or STEPCAT DD 
statement unless: 

• The object's entry is in the master catalog, or 

• The first qualifier of the object f s name is the 
catalog's name or alias. 

When INFILE and its DD statement are not specified for an 
object that is to be exported, an attempt is made to 
dynamically allocate it. 

Abbreviation: I FIL E 

INHIBITSOURCE1 N Q INHI BJIS B UB QE 

specifies whether the original data records (the data 
records of the source cluster or alternate index) can be 
accessed for any operation other than retrieval after a 
copy is exported. This specification can later be altered 
through the ALTER command. 

INHIBITSOURCE 

specifies that the source object in the original 
system cannot be accessed for any operation other than 
retrieval. This parameter can be specified only when 
the object is to be temporarily exported^. (A backup 
copy of the object is made and the object itself 
remains in the original system.) 

Abbreviation: INHS 

NOINHIBITSOURCE 

specifies that the original data records in the 
original system can be accessed for any kind of 
operation. 

Abbreviation: NINHS 
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EXPORT 


t 


INHIBITTARGET | MI MIM 1 IM SEI 

specifies whether the data records copied into the target 4 

alternate index or cluster can be accessed for any {. 

operation other than retrieval after they have been 
imported to another system. This specification can be 
altered through the ALTER command. 

INHIBITTARGET 

specifies that the target object cannot be accessed 
for any operation other than retrieval after it has 
been imported into another system. 

Abbreviation: INHT 


NOINHIBITTARGET 

specifies that the target object can be accessed for 
any type of operation after it has been imported into 
another system. 

Abbreviation: NINHT 


PURGE 1MOR URGE 

specifies whether the cluster or alternate index to be 
exported is to be deleted from the original system 
regardless of the retention period specified in a TO or FOR 
parameter when the object was defined. 

This parameter can be specified only if the object is to be 
permanently exported, that is, deleted from the original 
system. 

PURGE 

specifies that the object is to be deleted even if the 
retention period has not expired. 

Abbreviation: PRG 

NOPURGE 

specifies that the object is not to be deleted unless 
the retention period has expired. 

Abbreviation: NPRG 

TEMPORARY | BI RMMEM1 

specifies whether the cluster or alternate index to be 
exported is to be deleted from the original system. 

TEMPORARY 

specifies that the cluster or alternate index is not 
to be deleted from the original system. The object in 
the original system is marked as temporary to indicate 
that another copy exists and that the original copy 
can be replaced. 

To replace the original copy, a portable copy created 
by an EXPORT command must be imported to the original 
system. The IMPORT command deletes the original copy, 
defines the new object, and copies the data from the 
portable copy into the newly defined object. 

Note: Be sure to properly protect the file of the 

temporary object if you want to deny unauthorized 
access to that file. 

Abbreviation: T EMP 

PERMANENT 

specifies that the cluster or alternate index is to be 
deleted from the original system. Its storage space 
is freed. If its retention period has not yet 
expired, you must also code PURGE. 

Abbreviation: PERM 


4 " 
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EXPORT EXAMPLES 


Exporting a Key-Sequenced Cluster: Example 1 

In this example, a key-sequenced cluster, D40.EXAMPLE.KSDS1, is 
exported from a user catalog, D27UCAT1. The cluster is copied 
to a portable file, TAPE2, and its catalog entries are modified 
to prevent the cluster f s data records from being updated, added 
to, or erased. 

//EXP0RT1 JOB 

//STEP1 EXEC PGM=IDCAMS 

//RECEIVE DD DSNAME=TAPE2,UNIT=CTAPE,,DEFER), 

// DISP=NEN,VOL=SER=003030, 

// DCB=(BLKSIZE=6000,DEN=3),LABEL=(1,SL) 

//SYSPRINT DD SYS0UT=A 

//SYSIN DD x 

EXPORT - 

D40.EXAMPLE.KSDS1 - 
OUTFILEC RECEIVE) - 
TEMPORARY - 
INHIBITSOURCE 
/X 

Job control language statement: 

• RECEIVE DD, which describes the portable file, a magnetic 
tape file, that is to receive a copy of the cluster's 
records. The DCB BLKSIZE parameter overrides the EXPORT 
default of 2048 to improve performance. 

The EXPORT command copies the key-sequenced cluster, 

D40.EXAMPLE.KSDS1, to a portable file, TAPE2, and modifies the 
cluster's catalog entries Cits cluster, data, and index 
entries). Access method services attempts to dynamically 
allocate D40.EXAMPLE.KSDS1. Because the high-level qualifier of 
the cluster name is the name of the alias of D27UCAT2, the 
cluster can be allocated without specifying a JOBCAT or STEPCAT 
DD statement. The EXPORT command's parameters are: 

• D40.EXAMPLE.KSDS1, which identifies the cluster to be 
exported. Because the cluster is not password-protected, no 
password is provided with the cluster's entryname. 

• OUTFILE, which points to the RECEIVE DD statement. The 
RECEIVE DD statement describes the portable file, TAPE2, 
that is to contain a copy of the cluster. 

• TEMPORARY, which specifies that the cluster is not to be 
deleted. The cluster's catalog entry is marked "temporary" 
to indicate that another copy of the cluster exists and that 
the original copy can be replaced. (See the IMPORT Example, 
"Importing a Key-Sequenced Cluster.") 

• INHIBITSOURCE, which specifies that the copy of the cluster 
that remains in the original system, as a result of 
TEMPORARY, cannot be modified. User programs are allowed 
only to read the cluster's records. 
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Exporting an Entry-Sequenced Cluster: Example 2 

In this example, an entry-sequenced cluster is exported to a 
portable file and then deleted from the system. 

//EXP0RT2 JOB 

//STEP1 EXEC PGM=IDCAMS 

//RECEIVE DD DSNAME=TAPE1,UNIT=(TAPE,,DEFER), 

// VOL=SER=001147,LABEL=(1,SL),DISP=NEW 

//SYSPRINT DD SYS0UT=A 

//SYSIN DD X 

EXPORT - 

D50.EXAMPLE.ESDS1 - 
OUTFILECRECEIVE) - 
PURGE 
/x 

Job control language statement: 

• RECEIVE DD, which describes the portable file, TAPE1, that 
is to contain a copy of the exported entry-sequenced 
cluster. 

The EXPORT command copies the entry-sequenced cluster, 

D50.EXAMPLE.ESDS1, to a portable file, TAPE1. The cluster is 
deleted from the system after it is copied into the portable 
file. Access method services attempts to dynamically allocate 
D50.EXAMPLE.ESDS1. Because the high-level qualifier of the 
cluster is the name of the alias of the catalog D27UCAT2, the 
cluster will attempt to be dynamically allocated without 
specifying a JOBCAT or STEPCAT DD statement. The EXPORT 
command f s parameters are: 

• D50.EXAMPLE.ESDS1, which identifies the entry-sequenced 
cluster to be exported. When a cluster is exported, its 
master password is required if it is password-protected. 

• OUTFILE, which points to the RECEIVE DD statement. The 
RECEIVE DD statement describes the portable data set, TAPE1, 
that is to receive a copy of the cluster. 

• PURGE, which allows the cluster to be deleted regardless of 
its retention period or date. 

Because EXPORT defaults to PERMANENT, access method services 
assumes the cluster is to be deleted after TAPE1 contains a copy 
of it. 

Because EXPORT defaults to NOINHIBITTARGET, access method 
services assumes the cluster can be updated (by users of the 
other system) when it is imported to another system. 
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EXPORTRA 


BffiffiBIBA 


The EXPORTRA command recovers VSAM and non-VSAM catalog entries 
from catalog recovery areas# and recovers data for VSAM clusters 
and alternate indexes by means of catalog recovery areas. This 
command is for use with _ OJPJLV> 

The format of the EXPORTRA command is: 


EXPORTRA 

OUTFILEC ddname) 

CRA( 


(ddnamel 


CALL! INFILE(ddname2)ll 


ENTRIES! 


(entrvnamet .ddnam.e.3.]) 

((entrvnamel ddname31)...1) 1 


NONE}) 


I(ddnamel. 

t FORCE 1 NOFORCE1 
(MASTERPIU password) 1 


EXPORTRA can be abbreviated: XPRA 

EXPORTRA PARAMETERS 


Required Parameters 

OUTFILECddrmm^) 

identifies the DD statement that describes the data set 
(usually a movable disk pack or magnetic tape reel) that is 
to contain a copy of the VSAM objects and catalog entries 
identified with the CRA parameter. 

With the exception of block size# the data set 
characteristics of the target data set that is to contain 
the cluster to be exported should not be specified. Block 
size is defaulted by the EXPORTRA command to 2048. Block 
size may be specified in the DD statement to override this 
default and improve performance. 


The characteristics of the target data set are described in 
"For a Target Data Set" on page 10. 

Abbreviation: OFILE 


CRAC 

tddnami s i 

CALLC IHFILEtdrinaJM2ni 
ENTRIES! 

Ijfeoicynaaat d dn am&53) 
n e a tryn a m et d dn amaS*)»• • 1)1 
NONE}) 

[ td dn am. fi I* 

The CRA parameter and its subparameters describe the 
catalog recovery area(s) to be referred to# identify the 
specific entries to be copied from the catalog recovery 
area# and specify the volumes that contain the entries 1 
data. A separate set of subparameters is specified to 
describe each catalog recovery area to which it refers. 


ddnamel 

identifies the DD statement that describes a volume to 
whose catalog recovery area is referred. Each ddnamel 
you specify is followed by one of the following 
subparameters# which specifies the action to be taken 
with regard to the catalog recovery area: 
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ALL 

specifies that each entry in ddnamel v s catalog N 

recovery area is to be copied to the OUTFILE data set. 

In addition* the contents (that is* data records in 
logical sequential order) of each VSAM cluster and 
alternate index are copied* following the copy of the 
catalog recovery area entry. 

If any of these VSAM clusters or alternate indexes has 
data that resides on volumes other than that 
identified via ddnamel* you use INFILE to describe all 
the volumes. 

INFILE(M0ime_2) 

identifies the DD statement that describes multiple 
volumes to be used in the recovery process. INFILE is 
required if the VSAM clusters and/or alternate indexes 
whose entries are contained in ddnamel*s catalog 
recovery area reside on multiple volumes. The ddname2 
DD statement should include all volumes containing the 
data set* including the recovery area volume. 

Abbreviation: IFIL E 

ENTRIES( 

(eo±Q\matagC d doa ma S *) 

C cj. dn am.e.i.3)«♦»I) 

names each entry in the catalog recovery area that is 
to be copied to the OUTFILE data set. All other 
entries in the catalog recovery area are not copied. 

mlrxrmme 

names an object whose catalog entry is contained 
in the ddnamel volume^ catalog recovery area. 

You can specify the entryname of the following 

entry types: alternate index* cluster* and , N 

non-VSAM. 

When you specify a cluster entry* the clusters 
data and index entries and all associated path 
entries are also copied. In addition* the 
clusters contents (that is* its data records* in 
logical sequential order) are copied* following 
the copies of the clusters catalog entries. 

When you specify an alternate index entry* the 
alternate index f s entries and contents and all 
associated path entries are copied as though it 
were a key-sequenced cluster. 

identifies the DD statement that describes each 
volume that contains part of the cluster or 
alternate index. ddname3 is ignored when 
specified for a non-VSAM entry. 

ddname3 is required when the entry is a VSAM 
cluster or alternate index whose data resides on 
volumes other than the volume identified with the 
ddnamel DD statement. The ddname3 DD statement 
must also include the volume referenced by the 
ddnamel DD statement. 

Abbreviation: ENT 


NONE 

specifies that no object in the volume f s catalog 
recovery area is to be copied. You must specify 
ddnamel NONE for each volume referenced in a ddname2 
or ddname3 DD statement if you do not want the entries 
in its catalog recovery area to be copied. 

Note: If ddname2 contains both multiple volume and 

single volume entries* a NONE statement is required to 
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prevent processing of the single volume entries that 
exist on the second and subsequent volumes. The NONE 
parameter must be specified before the ALL parameter. 
(See "Using EXPORTRA for All Entries on Multiple 
Volumes: Example 2 n on page 182.) 


Optional Parameters 


FORCE I MSE. QRCE 

specifies whether the catalog entry's copy is to be copied 
from the catalog recovery area; even though the copy itself 
might be inaccurate. 

FORCE 

specifies that the object's catalog entry copy is 
copied from the volume f s catalog recovery area; even 
though a loss of data integrity might result. Time 
stamp and extent mismatches are ignored. 

Abbreviation: FRC 

NOFORCE 

specifies that the catalog recovery area f s copy is not 
copied if it is not accurate; and the EXPORTRA command 
terminates with an error message. 

Abbreviation: NFRC 

MASTERPW(fis^SV^) 

specifies the master catalog's master password. The master 
catalog's master password is required when the master 
catalog is password-protected. RACF: The alter RACF 
authority to the master catalog is required. 

Abbreviation: MRPW 
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EXPORTRA EXAMPLES 


Using EXPORTRA for All Entries on One Volume: Example 1 


This example shows the EXPORTRA function for one volume, VO, 
owned by the VSAM master catalog. All the entries contained in 
the catalog recovery area on VO and the data sets themselves are 
copied to a SAM data set on another disk volume. All the data 
sets reside entirely within the one volume. 


//EXPORTRA JOB ... 

//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=A 

//VLVO DD UNIT=DISK,V0L=SER=V0,AMP= 1 AMORG 1 ,DISP=0LD 
//VOLOUT DD UNIT=DISK,V0L=SER=333GQ3,DSN=QUT.FILE, 

// DISP=(NEW,KEEP),SPACE=CCYL,(5,1)), 

// DCB=BLKSIZE=6000 

//SYSIN DD X 
EXPORTRA - 

OUTFILE(VOLOUT) - 
CRA C - 
(VLVO ALL)) 


/x 


Job control language statements: 

• VLVO DD, which identifies and allocates the volume whose 
catalog recovery area contents are to be copied. The data 
sets reside wholly within the one volume. 

• VOLOUT DD, which identifies the sequential file that is to 
receive the copied data sets and catalog recovery records. 
The DCB BLKSIZE parameter overrides the EXPORTRA default of 
2048 to improve performance. 


The EXPORTRA command copies everything appearing in the catalog 
recovery area of volume VO. The EXPORTRA command parameters 
are: 


• OUTFILE, which is required and identifies the sequential 
access method (SAM) non-VSAM data set that is to receive the 
copied information. 

• CRA, which is required and identifies the catalog recovery 
area and volume from which the copy is to take place. VLVO 
identifies the DD statement for the catalog recovery volume. 
The ALL subparameter specifies that all entries are to be 
copied from the catalog recovery area. The INFILE 
subparameter is not required, because the data sets are 
contained wholly within the one volume. 


Using EXPORTRA for All Entries on Multiple Volumes: Example 2 

This example shows the EXPORTRA function for one volume owned by 
the VSAM master catalog. All data sets contained on the volume, 
VO, and their corresponding CRA entries describing the data sets 
are copied to a sequential (SAM) data set on a tape volume. The 
catalog recovery area contains data sets which reside on volumes 
VI and V2 in addition to the recovery volume, VO. The entries 
in the catalog recovery areas of the additional volumes are not 
to be recovered. 
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//EXPGRTRA JOB 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYS0UT=A 

//VLVO DD UNIT=DISK,VOL=SER=V0,AMP= l AMGRG f , 

// DISP=OLD 

//VLV1 DD UNIT=DISK,VOL=SER=Vl,AMP='AMORG f , 

// DISP=OLD 

//VLV2 DD UNIT=DISK, V0L=SER=V2,AMP= 1 AMORG 1 , 

// DISP=QLD 

//VOLA DD UNIT=(DISK,3),VOL=SER=(V0,V1,V2), 

// AMP= f AMORG',DISP=OLD 

//VOLOUT DD DSN“OUT.FILE,LABEL=(1,SL), 

// DISP=(NEW,KEEP), 

// UNIT=TAPE,V0L=SER=TAPE01, 

// DCB=(BLKSIZE=8192,DEN=3) 

//SYSIN DD X 

EXPORTRA - 

OUTFILECVOLOUT) - 
CRA C ~ 

(VLVO ALL INFILECVOLA)) - 
(VLV1 NONE) - 
(VLV2 NONE) - 
(VLV1 ALL))- 
MASTERPW(MCATMRPW) 

/x 

Job control language statements: 

• VLVO DD, which identifies the volume whose catalog recovery 
area contents are to be exported. 

• VLV1 DD, which identifies a volume containing part of a 
multiple volume data set to be exported and single volume 
data sets to be exported. 

• VLV2 DD, which identifies a volume containing part of a 
multivolume data set to be exported. The catalog recovery 
area contents are not to be exported. 

• VOLA DD, which identifies all the volumes containing the 
data sets to be exported. 

• VOLOUT DD, which identifies the sequential tape file that is 
to receive the exported data sets and catalog recovery 
records. The DCB BLKSIZE parameter overrides the default of 
2048 to improve performance. 

The EXPORTRA command copies every entry appearing in the catalog 
recovery area of volume VO and the data sets described by the 
CRA entries. Because they contain part of multivolume data 
sets, two additional volumes, VI and V2, are referred to, but 
the entries in their catalog recovery areas are not exported. 

The EXPORTRA command parameters are: 

• OUTFILE, which is required and identifies the sequential 
(SAM) non-VSAM data set that is to receive the exported 
information. 

• CRA, which is required and identifies the catalog recovery 
area and volumes from which the entries are to be copied. 
VLVO identifies the DD statement of the recovery volume. 

The ALL subparameter specifies that all entries in the 
catalog recovery area of the volume identified by VLVO are 
to be copied. 

INFILE, which is required because the data sets to be copied 
are contained on multiple volumes. VOLA refers to the DD 
statement that identifies these multiple volumes, including 
the recovery volume. 

VLV1 NONE, which is required to prevent processing of single 
volume entries that exist on this volume that is referenced 
in the INFILE subparameter. This subparameter must precede 
VLV1 ALL. 
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VLV2 NONE, which is required because the volume it 

identifies is referenced in the INFILE subparameter. / ^ 

p 

VLV1 ALL is required and identifies the single volume data 
sets. This subparameter must come after VLVl NONE. 

• MASTERPW, which specifies the master password of the master 
catalog. This parameter is required when the master catalog 
is password protected. 


Using EXPORTRA for Selected Entries* Example 3 

This example shows the EXPORTRA function for selected entries 
from the catalog recovery area of one volume owned by the VSAM 
master catalog. Three data sets and their corresponding entries 
from the catalog recovery area on volume VO are copied to a 
sequential (SAM) data set on another disk volume. The remainder 
of the data sets and the catalog recovery area entries are not 
copied. Two of the selected data sets are multivolume VSAM data 
sets. The data sets and their corresponding entries in the 
catalog recovery areas of the additional volumes are not 
recovered. 

//EXPORTRA 
//STEP1 
//SYSPRINT 
//VLVO 
// 

//VLVl 
// 

//VLV2 
// 

//VOLA 
// 

//VOLB 
// 

//VOLOUT 
// 

//SYSIN 

EXPORTRA - 

OUTFILE(VOLOUT) - 
CRA ( - 

(VLVO ENTRIES ( - 

(LARGE.DATASET.A VOLA) - 
(LARGE.DATASET.B VOLB) - 
(LARGE.DATASET.C))) - 
(VLVl NONE) - 
(VLV2 NONE)) - 
FORCE 
/x 


JOB 

EXEC PGM=IDCAMS 

DD SYSOUT=A 

DD UNIT=DISK,AMP= f AMQRG f ,DISP=OLD, 

VOL=SER=VO 

DD UNIT=DISK,AMP='AMORG f ,DISP=0LD, 

V0L=SER=V1 

DD UNIT=DISK,AMP= f AMORG , ,DISP=QLD, 

V0L=SER=V2 

DD UNIT=(DISK,3),AMP= f AM0RG f ,DISP=0LD, 

VOL=SER=(VO,V1,V2) 

DD UNIT=(DISK,2),AMP= f AM0RG f ,DISP=0LD, 

VGL=SER=(V0,V1) 

DD UNIT=DISK,VOL=SER=333Q03,DSN=QUT.FILE, xx 

DISP=(NEW,KEEP),SPACE=(CYL,(5,1)) 

DD X 


Job control language statements: 

• VLVO DD, which identifies the volume whose catalog recovery 
area contains the entries for the three VSAM data sets to be 
copied. 

• VLVl and VLV2 DD, each of which identifies a volume 
containing part of a multivolume data set but whose catalog 
recovery area contents are not to be copied. 

• VOLA DD, which identifies the multivolumes of 
LARGE.DATASET.A. 

• VOLB DD, which identifies the multivolumes of 
LARGE.DATASET.B. 

• VOLOUT DD, which identifies the sequential file that is to 

receive the copied data sets and catalog recovery records. f 

The EXPORTRA command exports the three entries (LARGE.DATASET.A, 

LARGE.DATASET.B, and LARGE.DATASET.C) from the catalog recovery 

area on volume VO. Because they contain part of multivolume 
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data sets, two additional volumes are referred to, but the 
entries in their catalog recovery areas are not exported. The 
EXPORTRA command parameters are: 

• OUTFILE, which is required and identifies the non-VSAM data 
set that is to receive the exported information. 

• CRA, which is required and identifies the catalog recovery 
area and volumes from which the export is to take place. 

VLVO identifies the DD statement of the recovery volume. 

The ENTRIES subparameter identifies the three entries which 
are to be copied. 

LARGE.DATASET.A requires the VOLA subparameter because the 
VSAM data set is contained on three volumes. Similarly, 
LARGE.DATASET.B requires the VOLB subparameter. However, 
LARGE.DATASET.C is contained wholly within the catalog 
recovery volume, and, therefore, does not require an 
additional ddname3 subparameter. 

The VLV1 NONE and VLV2 NONE subparameters are necessary, 
because the volumes they identify are referenced in previous 
ddname3 subparameters (VOLA and VOLB); however, the contents 
of their catalog recovery areas are not to be copied. 

• FORCE, which specifies that timestamp mismatches are to be 
ignored. 
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I I1PQ RI....C PNNE C T 


The IMPORT CONNECT command connects a user catalog. The format 
of this command is: 


IMPORT 

CONNECT 


OBJECTS((usercaiogas 


DEVICETYPEtdevtvoe1 


VOLUMEStvolser))) 


[ CATALOG (ma&fcsr.p.ainam.e t /password 3) 1 


IMPORT CONNECT PARAMETERS 


Required Parameters 


CONNECT 

specifies that a user catalog is to be connected. The user 
catalog is connected to the master catalog in the receiving 
system. When CONNECT is coded, OBJECTS must also be coded 
to name the catalog and to identify the volume serial 
number and device type of the volume that contains the user 
catalog. 

Abbreviation: CON 

OBJECTSC Cys ericatnatO.Q 
DEVICETYPEC devtvpe ) 

VOLUMES(ypJLsejr))) 

specifies the user catalog to be connected. 

Msenga t p a me . 

specifies the name of the user catalog being 
connected. 

DEVICETYPEt devtvpe 3 

specifies the device type of the volume that contains 
a user catalog that is to be connected. You can 
specify a device type for any direct access device 
that is supported. 

Abbreviation: DEVT 

VOLUMES( volser 3 

specifies the volume on which the user catalog 
resides. 

VOLUMES is required when a user catalog is to be 
import connected. VSAM user catalogs may only be on 
one volume so only one volume should be specified when 
connecting a VSAM user catalog. 


Optional Parameters 


CATALOG (salnamft I /p as^wpcd 3) 

specifies the name of the catalog in which the catalog you 
are connecting is to be defined. This parameter is 
required when the catalog is password-protected or when you 
want to direct the catalog*s entry to a particular catalog 
other than the master catalog. 

salaams 

is the name of the catalog in which the catalog you 
are connecting is to be defined. If the specified 
catalog is not the master catalog, the catalog must be 
identified by a JOBCAT or STEPCAT DD statement. If 
you are import connecting a user catalog, the 
specified catalog is usually the master catalog. 
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password 

specifies the master catalog's update- or higher-level 
password. RACF: The update or higher RACF authority 
to the master catalog is required. 


Abbreviation: CAT 


Chapter 4. Functional Command Format 187 





IMPORT CONNECT 
IMPORT CONNECT EXAMPLE 


Importing to Connect a User Catalog: Example 1 

In this example/ a user catalog/ D27UCAT1/ is connected to the 
system's master catalog/ AMAST1. This example reconnects the 
user catalog/ D27UCAT1/ that was disconnected in the EXPORT 
DISCONNECT example. 

//IMP0RT1 JOB ... 

//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=A 
//SYSIN DD X 
IMPORT - 

OBJECTSC - 

(D27UCAT1 - 
V0LUMECVSER02) - 
DEVICETYPEC3380) ) - 
) - 

CONNECT - 

CATALOGCAMAST1/MASTMPW1) 

/X 

The IMPORT command builds a user catalog connector entry that 
identifies the user catalog D27UCAT1 in the master catalog 
AMAST1. Its parameters are: 

• OBJECTS/ which is required when a user catalog is being 
imported. The subparameters of OBJECTS identify the user 
catalog/ D27UCAT1; the user catalog's volume/ VSER02; and 
the device type of the user catalog's volume/ 3380. 

• CONNECT/ which specifies that the user catalog connector 
entry is to be built and put in the master catalog to 
connect the user catalog to the master catalog. CONNECT is 
required when a user catalog is being reconnected. 

• CATALOG/ which identifies the master catalog/ AMAST1/ and 
specifies its update- or highei—level password/ MASTMPW1. 
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IMESRI 

The IMPORT command restores a VSAM cluster or alternate index 
from a portable data set created by the EXPORT command. The 
format of this command is: 


IMPORT 


CINFILECddnamfi) I INDATASET( entrvname )> 
C OUTFILE C ri doama £ /Ra ss apxri 3) I 

OUTDATASET( ent rvname l / passwo rd 3)} 

[ERASE|NOERASE3 
[INTOEMPTY] 

[OBJECTS 


C (£n±ojmm£ 

[FiLECdrinams)] 

[(KEYRANGES(C lowkev hiahkev ) 
E(l£fed££Y MshkSY). •. 3 )1 
[ NEWNAME( n . ^ a §m ^) 3 
[ORDERED IUN0RDERED3 
[ VOLUMESCyjal§£E[ xstlS&Z* ..3)3) 
C [ en . t .r.ynam Q ...)...))] 

[PURGE 1NQPURGE 3 
[ SAVRAC1N9SMRAP. 3 


[CATALOGC^a±namet/ p a s s.wQr d 3)3 


IMPORT may be abbreviated: IMP. 


IMPORT PARAMETERS 


Required Parameters 


lNFlLE(_4dmm £ ) I INDATASET( ^ Di xy n^mg) 

specifies the name of a DD statement or names the portable 
data set that contains a copy of the cluster or alternate 
index to be imported. 

INFILE(ddaame) 

specifies the name of a DD statement that identifies 
the portable copy of the cluster or alternate index to 
be imported. 

If a nonlabeled tape or a direct access data set 
created by DOS/VS access method services contains the 
copy, the following DCB parameters must be specified 
on the referenced DD statement: 

• BLKSIZE. If you specified BLKSIZE when the 
cluster or alternate index was exported, you must 
specify the same block size value for IMPORT. If 
you did not specify a block size for EXPORT, a 
default value of 2048 was used. Consequently, if 
you do not specify BLKSIZE for IMPORT, IMPORT sets 
the block size to 2048. 

• LRECL. LRECL is based on the maximum record size 
of the exported VSAM data set. Maximum record 
size is determined by the value specified via the 
maximum subparameter of the RECORDSIZE parameter 
of the DEFINE CLUSTER or DEFINE ALTERNATEINDEX 
command when the data set was defined. 

• RECFM. Must be VBS. 

Abbreviation: I FILE 

INDATASET( entrvname ) 

specifies the name of the portable data set that 
contains a copy of the cluster or alternate index to 
be imported. 


Chapter 4. Functional Command Format 189 





IMPORT 


If INDATASET is specified? the portable data set is 

dynamically allocated. The entryname must be 

cataloged in a catalog that is accessible by the 

system into which the entry is to be imported. J 

Abbreviation: IDS 

OUTFILEC.ddaame l / flfr g s wjard I)1 OUTDATASET! entrvname E/ password l) 
specifies the name of a DD statement or the name of a 
cluster or alternate index to be imported. 

When you use OUTFILE or OUTDATASET to describe the data 
set? you must identify the data set f s catalog with a JOBCAT 
or STEPCAT DD statement unless* 

• The data set f s entry is in the master catalog? or 

• The first qualifier of the data set"s qualified name is 
the catalog*s name or alias. 

Notes: 

1. When importing a cluster that was permanently exported? 
the OUTFILE parameter should be used. 

2. If a concatenated JOBCAT or STEPCAT DD statement is 
used? the catalog to be imported must be identified in 
the first DD statement? unless the catalog is specified 
with the CATALOG parameter. 

OUTFILE C ddnqmQ l / B a SSM& Ed 1 ) 

specifies the name of a DD statement that identifies 
the data set name and volume(s) of the cluster or 
alternate index to be imported. 

If the object was permanently exported and/or you are 
importing to a volume other than the original volume? 
the DD statement specifies the name of the cluster or 
alternate index as DSNAME? the volume serial 
number(s)? the device type? DISP=0LD? and AMP= l AM0RG l . 

If the object has its data and index components on 
different device types? do not specify OUTFILE—use 
OUTDATASET. 

If NEWNAME is specified for the cluster or alternate 
index entry? the data set name on the DD statement 
must be the same as the new name. The volume that is 
to receive the imported cluster or alternate index 
must be owned by a VSAM catalog. Also? this should be 
the same name declared on the NEWNAME parameter. 

Failure to do so will result in the deletion of the 
original cluster. 

is the update- or highei—level password of the 
target object. You must supply the password when 
the target data set is empty. (See the VOLUMES 
parameter for more information about importing 
into an empty data set.) Otherwise? IMPORT 
obtains the required VSAM data set passwords from 
the portable data set. RACF: The update or 
higher RACF authority to the target object is 
required. 

Abbreviation: 

OUTDATASET tt /p^jSSbLPXd I) 

specifies the name of the cluster or alternate index 
that is to be imported. When you specify OUTDATASET? 
the VSAM data set you identify is dynamically 
allocated. 
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You may use concatenated DD statements if the object 
was permanently exported and its data and index 
components are on different device types. The first 
DD statement specifies the name of the cluster or 
alternate index as the DSNAME, the volume serial 
numbers and device type of the data component/ 
DISP=QLD, and AMP= , AM0RG*. The second DD statement 
specifies the name of the index component as the 
DSNAME, the volume serial numbers and device type of 
the index component, DISP=0LD, and AMP =l AM0RG f . 

If NEWNAME is specified for the cluster or alternate 
index entry, entryname must be the same as the new 
name. Also, this should be the same name declared on 
the NENNAME parameter. Failure to do so will result 
in the deletion of the original cluster. 

pas swo r d 

is the update- or highei—level password of the 
target object. (See password under OUTFILE for 
password requirements of the target data set.) 
RACFs The update or higher RACF authority to the 
target object is required. 

Abbreviation: ODS 


Optional Parameters 


CATALOG tgajtoamfi£/ passwo rd 1 ) 

specifies the name of the catalog in which the imported 
object is to be cataloged. This parameter is required when 
the catalog is password-protected. 

satn ame 

specifies the name of the catalog in which the entry 
to be imported is to be defined. 

JBMSWJ&Cd 

specifies the catalog's update- or highei—level 
password. RACF: The update or higher RACF authority 
to the catalog is required. When you import an 
alternate index whose base cluster is 
password-protected, you should supply the catalog f s 
master password. RACF: The alter RACF authority to 
the catalog is required. Otherwise, you (or the 
operator) will be prompted to supply the base 
cluster's master password. RACF: The alter RACF 
authority to the base cluster is required. When you 
import an integrated catalog facility user catalog and 
INTOEMPTY is not specified, the master password of the 
master catalog is required. RACF: The alter RACF 
authority to the master catalog is required. 

Abbreviation: CAT 

ERASE I NOERASE 

specifies whether the data component of the cluster or 
alternate index is to be erased (that is, overwritten with 
binary zeros). This parameter can be used only when you 
are importing the object into the system from which it was 
previously exported with the TEMPORARY option. This 
parameter overrides whatever was specified when the object 
was defined or last altered. 

ERASE 

specifies that the data component is to be overwritten 
with binary zeros when the cluster or alternate index 
is deleted. If ERASE is specified, the volume that 
contains the data component must be mounted. 

Abbreviation: ERAS 
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NOERASE 

specifies that the data component is not to be 
overwritten with binary zeros when the cluster or 
alternate index is deleted. 

Abbreviation: N ERAS 


INTOEMPTY 

specifies that you are importing from the portable data set 
into an empty data set. If this parameter is not 
specified/ an attempt to import into an empty data set will 
fail. The password and RACF profiles associated with the 
empty data set will be retained. 

When importing into an empty data set/ the SAVRACINOSAVRAC 
parameter applies only to the paths imported and 
successfully defined over the empty data set. If the 
define of an exported path fails because a catalog entry 
with the same name already exists/ the path on the portable 
data set is ignored. 

Abbreviation; IEMPTY 


OBJECTS 

((fintcynams 

[FILE( ddname ]I 

{KEYRANGESt ( lowkev highkev lt( lowkev hiahkey )...})]■ 
INEMNAMEt newname 11 
IORDEREDI MNPRDE R EP I 
[VOLUMES( volser t volser .♦.])]) 

1( . g o tryn a ^e . ♦.)...!)] 

specifies the new or changed attributes for 
alternate index/ or any associated paths to 


the cluster/ 
be imported. 


Access method services matches each entryname you specify 
through the OBJECTS parameter against the name of each 
object on the portable data set. When a match is found/ 
the information specified by OBJECTS overrides the 
information on the portable data set. 


^ jpAry-nam e 

specifies the name of the data component/ index 
component/ cluster/ alternate index/ or path for which 
attributes are being specified. The entryname must 
appear on the portable data set; otherwise/ the 
parameter list will be ignored. 

Abbreviation; OBJ 


FILE(ddnanm) 

specifies the name of a DD statement that identifies 
the volumes allocated to the data and index components 
of a key-sequenced cluster or an alternate index. 

This parameter is used when the components are defined 
as unique and when the data and index components 
reside on different device types. FILE can be coded 
twice within the OBJECTS parameter; once in the 
parameter set for the index component and once in a 
second parameter set for the data component. 

If you do not specify FILE/ the required volumes are 
dynamically allocated. The volumes must be mounted as 
permanently resident and reserved. 

KEYRANGESt(i 2 Hkjgy high)11l.Qwk. e y hiahkey)••• 1) 

specifies portions of a key-sequenced cluster or 
alternate index to be placed on separate volumes. 

The data is divided/ by key, among the volumes as 
contained in the portable data set or as specified in 
the VOLUMES parameter. 



( *f 
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If a volume serial number is duplicated on the 
portable data set or in VOLUMES* multiple key ranges 
of an alternate index or cluster attribute are placed 
on that volume. 

If the number of volumes is greater than the number of 
key ranges* the excess volumes are used for overflow 
records from any key range without consideration of 
range boundaries. If there are fewer volumes than key 
ranges* the excess key ranges are placed on the last 
volume specified. 

By using the KEYRANGE parameter* you may specify key 
range pairs for a key-sequenced data set that 
previously was not divided by key or that was divided 
in different key range groups. 

The maximum number of key range pairs is 20. Key 
ranges must be in ascending order* and may not 
overlap. Gaps may exist within a specified set of 
ranges* but records cannot be inserted within a gap. 

When you specify KEYRANGES* the entryname can be 
either the cluster or alternate index name or the name 
of the data component. If you specify KEYRANGES with 
the cluster or alternate index name* the values 
specified are defined for the data component. If you 
specify KEYRANGES with the data component name* the 
values are defined for the data component* and any 
specification of KEYRANGES with the cluster or 
alternate index name is overridden. 

Keys can contain 1 to 64 characters; if coded in 
hexadecimal* they can contain 1 to 128 hexadecimal 
characters. All EBCDIC characters are allowed. 

lPMkfiy 

specifies the low key of the key range. If 
lowkey is shorter than the actual keys* it will 
be padded with binary zeros. 

hiahk ey 

specifies the high key of the key range. If 
highkey is shorter than the actual keys* it will 
be padded with binary ones. 

Abbreviation: KRNG 

NEWNAMEt newname ) 

specifies the new name of an imported cluster or 
alternate index or its components* or an associated 
path. When you specify NEWNAME* only the name 
specified as entryname is changed. 

If you are specifying a new name for a cluster or 
alternate index that was exported with the TEMPORARY 
option and it is being imported back into the original 
system* you must also rename each of its components. 

Abbreviation: NEWNM 

ORDERED 1 UMPJRPEREB 

specifies whether volumes are to be used in the order 
in which they were listed when the data set was 
originally defined Cas contained on the portable data 
set) or in the VOLUMES parameter. 

If the data set is divided into key ranges* all the 
records within the range specified by the first 
low-key high-key pair are placed on the first volume; 
all the records within the second range are placed on 
the second volume* and so on. 
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If it is impossible to allocate volumes in the given 

order and ORDERED is specified, the command is ^ 

terminated. 

When you specify ORDEREDIUNORDERED, you can specify 
the cluster or alternate index name, the data 
component name or the index component name as 
entryname with the following results? 

• If ORDERED!UNORDERED is specified with the cluster 
or alternate index name, the specified attribute 
is defined for the data component. For a 
key-sequenced cluster or alternate index, the 
specified attribute is also defined for the index 
component. 

• If ORDERED I UNORDERED is specified with the data 
component name, the specified attribute is defined 
for the data component. Any specification of 
ORDERED|UNORDERED with the cluster or alternate 
index name is overridden. 

• For a key-sequenced cluster and for an alternate 
index, if ORDERED|UNORDERED is specified with the 
index component name, the specified attribute is 
defined for the index component. Any 
specification of ORDERED|UNORDERED with the 
cluster or alternate index name is overridden. 

If OBJECTS is specified and neither ORDERED or 
UNORDERED is specified, then UNORDERED is the default. 

Abbreviations: ORD and UNORD 

VOLUMES[ volser C volser .,.1) 

specifies the volumes on which the cluster or 
alternate index is to reside. 

If VOLUMES is not coded, the original volume is the 
receiving volume. 

If the portable data set was created with an EXPORT 
command using the PERMANENT option on a Release 1 
version of access method services (DOS/VS Release 29, 

0S/VS1 Release 2, 0S/VS2 Release 1.6, or 0S/VS2 
Release 2), this parameter is required. Portable data 
sets created by Release 1 using the PERMANENT option 
do not contain volume information. 

When you specify VOLUMES, you can specify the cluster 
or alternate index name, the data component name or 
the index component name as entryname with the 
following results: 

• If VOLUMES is specified with the cluster or 
alternate index name, the specified volume list is 
defined for the data component. For a 
key-sequenced cluster or alternate index, the 
specified volume list is also defined for the 
index component. 

• If VOLUMES is specified with the data component 
name, the specified volume list is defined for the 
data component. Any specification of VOLUMES with 
the cluster or alternate index name is overridden. 

• For a key-sequenced cluster or alternate index, if 

VOLUMES is specified with the index component 
name, the specified volume list is defined for the 
index component. Any specification of VOLUMES j- 

with the cluster or alternate index name is n 

overridden. \ 
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For clusters or alternate indexes# if multiple volumes 
are specified# they must be of the same device type. 

By repeating the OBJECTS parameter set for each 
component and including VOLUMES in each parameter set# 
you can have the data and index components on 
different volumes. Although the index and data 
components may reside on different device types# each 
volume of a multivolume component must be of the same 
type. 

If the receiving volume is of a type different from 
that which originally contained the cluster or 
alternate index# the job may be terminated because of 
allocation problems. Each space allocation quantity 
is recorded in a catalog entry as an amount of 
cylinders or tracks even if RECORDS was specified in 
the DEFINE command. 

When a cluster or alternate index is imported# the 
number of cylinders or tracks in the catalog entry is 
not modified# even though the object may be imported 
to reside on a device type other than what it was 
exported from. If an object is exported from a 
smaller DASD and imported to a larger DASD# more space 
is allocated than the object needs. Conversely# if an 
attempt is made to import an object that previously 
resided on a larger DASD to a smaller DASD# it may 
fail. 

You can avoid space allocation problems by defining an 
empty cluster or alternate index and identifying it as 
the target for the object being imported as described 
below: 

• Using the DEFINE command# define a new entry for 
the cluster or alternate index in the catalog to 
which it is to be moved. If space was allocated 
in RECORDS# you may specify the same quantity; if 
it was allocated in TRACKS or CYLINDERS# you must 
adjust the quantity for the new device type. If 
an entry already exists in the catalog for the 
object# you must delete that entry or use a 
different name in the DEFINE command. 

• Using the IMPORT command# load the portable data 
set into the newly defined cluster or alternate 
index. When IMPORT encounters an empty target 
data set# the exported catalog information is 
bypassed and only the data records are processed. 

Abbreviation: VOL 

PURGE 1M Q EUR 6B 

specifies whether the original cluster or alternate index 
is to be deleted and replaced# regardless of the retention 
time specified in the TO or FOR parameter. This parameter 
can be used only when you are importing the object into the 
original system from which it was exported with the 
TEMPORARY option. 

PURGE 

specifies that the object is to be deleted even if the 
retention period has not expired. 

Abbreviation: PRG 

NOPURGE 

specifies that the object is not to be deleted unless 
the retention period has expired. 

Abbreviation: NPRG 
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SAVRACINQSMMC 

specifies, for a RACF-protected object, whether existing 
profiles are to be used or whether new profiles are to be 
created. 

SAVRAC 

specifies that RACF data set profiles already existing 
for objects being imported from the portable data set 
are to be used. Typically, you would specify this 
option when replacing a data set with a portable copy 
made with an EXPORT TEMPORARY operation. SAVRAC will 
cause the existing profiles to be saved and used, 
rather than letting the system delete old profiles and 
create new, default profiles. 

The profiles will actually be redefined by extracting 
information from existing profiles and adding caller 
attributes. You should ensure that these added 
attributes are acceptable. 

The ownership creation group and access list will be 
altered by the caller of the SAVRAC option. 

Caution: You should ensure that valid profiles do 
exist for clusters being imported when SAVRAC is 
specified. If this is not done, an invalid and 
possibly improper profile may be "saved” and used 
inappropriately. 

NOSAVRAC 

specifies that new RACF data set profiles are to be 
created. This is usually the situation when importing 
a permanently exported cluster. 

A profile will be defined for the imported cluster if 
either the automatic data set protection option has 
been specified for you or if the exported cluster had 
a RACF indication in the catalog when it was exported. 

If you import into a catalog in which there is a 
component with a duplicate name that is marked as 
having been temporarily exported, it and any 
associated profiles will be deleted before the 
portable data set is imported. 
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IMPORT EXAMPLES 


Importing a Key-Sequenced Cluster: Example 1 

In this example^ a key-sequenced cluster/ D40.EXAMPLE.KSDS1, 
that was previously exported/ is imported. (See the previous 
EXPORT example/ "Exporting a Key-Sequenced Cluster.") OUTFILE 
and its associated DD statement are provided to allocate the 
data set. 

The original copy of D40.EXAMPLE.KSDS1 is replaced with the 
imported copy, TAPE2. Access method services finds and deletes 
the duplicate name/ D40.EXAMPLE.KSDS1/ in the catalog D27UCAT1. 
(A duplicate name exists/ because TEMPORARY was specified when 
the cluster was exported.) Access method services then 
redefines D40.EXAMPLE.KSDS1/ using the catalog information from 
the portable file, TAPE2. 

//IMP0RT2 JOB 

//STEP1 EXEC PGM=IDCAMS 

//SOURCE DD DSNAME=TAPE2/UNIT=(TAPE/,DEFER), 

// VOL=SER=003030/DISP=0LD/ 

// DCB=(BLKSIZE=60Q0/LRECL=479/DEN=3)/LABEL=(1/SL) 

//SYSPRINT DD SYS0UT=A 
//SYSIN DD X 
IMPORT - 

INFILECSOURCE) - 
0UTDATASETCD40.EXAMPLE.KSDS1) - 
CATALQGCD27UCAT1/USERMRPW) 

/x 

Job control language statement: 

• SOURCE DD/ which describes the portable data set, TAPE2. 
TAPE2 resides on a magnetic tape file that will not be 
mounted by the operator until access method services opens 
TAPE2 for processing. The block size parameter is included 
(even though it need not be, because the tape has a standard 
label and the information is contained in the data set 
header label) to illustrate the fact that the information 
specified when the data set is imported is required to be 
the same as was specified when the data set was exported. 

The LRECL parameter is not required/ because the maximum 
record size is 475 bytes and the default (block size minus 
4) is adequate. However/ by specifying a record size, the 
default is overridden and virtual storage is more 
efficiently used. To specify a record size, specify the 
size of the largest record plus 4. 

The IMPORT command copies the portable data set, TAPE2/ into the 
system and assigns it the name D40.EXAMPLE.KSDS1. When TAPE2 is 
copied/ access method services reorganizes the data records so 
that deleted records are removed and control intervals and 
control areas contain the specified free space percentages. The 
original copy of the cluster is deleted and replaced with the 
data records from the TAPE2 portable file. The IMPORT command f s 
parameters are: 

• INFILE/ which points to the SOURCE DD statement. The SOURCE 
DD statement describes the portable file, TAPE2/ to be 
imported. 

• OUTDATASET/ which gives the name of the data set being 
imported. Because the high-level qualifier of the data set 
is the name of the alias of the user catalog D27UCAT2/ 
access method services can dynamically allocate the cluster 
without specifying a JOBCAT or STEPCAT DD statement. 

• CATALOG/ which identifies the catalog/ D27UCAT1/ in which 
the imported cluster is to be defined. The catalog's 
update- or highei—level password is required. 
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Importing an Entry-Sequenced Cluster in a VSAM Catalog: Example 2 

In this example, an entry-sequenced cluster, D50.EXAMPLE.ESDS1, 
is imported from a portable file, TAPE1. This example is V ^ 

associated with EXPORT example, "Exporting an Entry-Sequenced 
Cluster." The cluster is defined in a different catalog than 
that from which it was exported, assigned a new name, and 
imported to a different volume. 

//IMP0RT3 JOB ... 

//STEP1 EXEC PGM=IDCAMS 

//SOURCE DD DSNAME=TAPE1,UNIT=(TAPE,,DEFER),DISP=0LD, 

// VOL=SER=OQ1147,LABEL=(1,SL) 

//SYSPRINT DD SYS0UT=A 
//SYSIN DD X 
IMPORT - 

INFILECSOURCE) - 
0UTDATASETCD4Q.EXAMPLE.ESDS3) - 
OBJECTSC - 

CD50.EXAMPLE.ESDS1 - 

NEWNAMECD40.EXAMPLE.ESDS3) - 
VOLUMESCVSER02) ) - 
) - 

CATAL0GCD27UCAT1/USERUPPW) 

/x 

Job control language statement: 

• SOURCE DD, which describes the portable file, TAPE1. TAPE1 
resides on a magnetic tape file that will not be mounted by 
the operator until access method services opens TAPE1 for 
processing. 

The IMPORT command moves the contents of the portable file, 

TAPE1, into the system. When TAPE1 is moved, access method 
services reorganizes the data records. The IMPORT command's 
parameters are: 

• INFILE, which points to the SOURCE DD statement. The SOURCE 
DD statement describes the data set to be imported, TAPE1. 

• OUTDATASET gives the name of the data set that is being 
imported; the name is the renamed cluster. Because the 
high-level qualifier of the data set name is the name of the 
alias of the catalog, D27UCAT1, the data set can be 
dynamically allocated without specifying a JOBCAT or STEPCAT 
DD statement. 

• OBJECTS, which changes some of the attributes for the object 
being imported: 

— D50.EXAMPLE.ESDS1, which identifies the entry-sequenced 

cluster as it is currently named on TAPE1. 

— NEWNAME, which specifies that the cluster's entryname is 
to be changed to D40.EXAMPLE.ESDS3. 

— VOLUMES, which identifies the new volume on which the 
cluster is to reside. 

• CATALOG, which identifies the catalog, D27UCAT1, that is to 
contain the cluster's catalog entry. The catalog's update- 
or highei—level password is required. 
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The IMPORTRA command restores catalog entries from a portable 
data set created by the EXPORTRA command. This command is for 
use with r e pqve .Pia b . lr9 .c at alo g s. o nly. 

The format of the IMPORTRA command is: 


IMPORTRA 


{INFILEl ddname )1 INDATASET( entryname )T 
[QUTFlLE(ddpama)3 
[OBJECTS[ 

t&nirmamg 

CDEVICETYPEStdfiicb^C . d aY-ly. • n 3 
[FILE(ridpafflfl)l 

EVOLUMES(y^JL^erC y j p laS£> ..3)3) 

E SAVRAC1 NQ5 A YRA C. 3 * * 


E CATALOG (.s ail rta me E /&a^sJh?QJC.d 3 ) 3 


IMPORTRA can be abbreviated: MPRA. 


IMPORTRA PARAMETERS 


Required Parameters 


INFILEt ddname ) 

names the DD statement that describes the portable data set 
(the data set that resulted when you issued the EXPORTRA 
command). If the portable data set resides on a nonlabeled 
tape or in a direct access data set created by DOS/VS 
access method services, the DCB BLKSIZE parameter must be 
specified on the referenced DD statement. 

If you specified BLKSIZE for the portable data set that was 
created when you executed your EXPORTRA job, you must 
specify the same block size for your IMPORTRA job. (Mote: 
If you did not specify a block size for EXPORTRA, a default 
value of 2048 was used. Consequently, if you do not 
specify BLKSIZE for IMPORTRA, IMPORTRA sets the block size 
to 2048.) All other characteristics of the portable data 
set are established by IMPORTRA. 

Abbreviation: I FIL E 

INDATASET C entrvname ) 

specifies the data set name of the portable data set (the 
data set that resulted when you issued the EXPORTRA 
command). Nhen you specify INDATASET instead of INFILE, 
the portable data set is dynamically allocated. 

Abbreviation: IDS 


Optional Parameters 


CATALOG ( E / p . ag s w p. n d3 ) 

identifies the target catalog. 

If you do not include the CATALOG parameter, the JOBCAT or 
STEPCAT catalogs are used. If you have not specified a 
JOBCAT or STEPCAT catalog, the VSAM master catalog is used. 
If you don't specify the CATALOG parameter when the target 
catalog is password-protected, the system operator will be 
prompted to supply the correct password. 
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names the catalog. When you specify a user catalog, 
you must describe and allocate the catalog with a 
JOBCAT or STEPCAT DD statement. 

password 

is the target catalog f s update- or higher-level 
password, if the catalog is password protected. If 
any of the data sets being imported is an alternate 
index whose base cluster is password-protected, you 
should supply the catalog f s master password. RACFs 
The update or higher RACF authority to the catalog is 
required. 

Abbreviation: CAT 
OBJECTS( 

ED£VICETYPES(.deyly^[ day ±£E&. ..1)1 
IFlLECridnamsU 

l VOLUMES yslser. .*3)3) 
l t^n tr y narne ...)... 3) 

The OBJECTS parameter group specifies new or changed 
attributes for objects on the portable data set. 

OBJECTS 

specifies new or changed attributes for a cluster, an 
alternate index, or a non~VSAM data set that is being 
imported. By specifying the OBJECTS parameter, you 
may override certain attributes contained on the 
portable data set. 

Access method services matches each entryname you 
specify against the name of each object on the 
portable data set. When a match is found, the 
information specified by OBJECTS overrides the 
information on the portable data set. 

Abbreviation: OBJ 

mtcmame 

specifies the object's entryname. You can 
specify the entryname and associated attributes 
for up to 255 objects. 

You can specify the entryname of these types of 
objects only: VSAM cluster or an alternate 
index, non-VSAM data set, user catalog, and a 
VSAM object's data or index component. 

DEVICETYPES(devtyEe l deytype...3) 

specifies the device type on which a user catalog 
being imported resides or the device type(s) on which 
a non-VSAM data set being imported resides. 

If entryname names a user catalog, you may specify 
only one device type. If entryname names a non-VSAM 
data set that resides on different device types, the 
device types listed in the DEVICETYPES parameter must 
be specified in the same order as the volume serial 
numbers listed in the VOLUMES parameter. 

This parameter can be specified only when the 
entryname names a non-VSAM data set or user catalog. 
For a non-VSAM data set or user catalog, if 
DEVICETYPES is not coded, the data set or user catalog 
must still reside on the same device type(s) as 
contained in the entry in the portable data set. 

Abbreviation: DEVT 
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FlLEIA d na n i Q ^ 

specifies the name of a DD statement that identifies 
the volumes allocated to the data and index components 
of a key-sequenced cluster or an alternate index. 

This parameter is required when the components are 
defined as unique and when the data and index 
components reside on different device types. 

When components reside on different device types/ FILE 
must be coded twice within the OBJECTS parameter; once 
in the parameter set for the index component and once 
in a second parameter set for the data component. If 
you do not specify FILE/ the required volumes are 
dynamically allocated. 

VOLUMES (yfilsgrC vglgjgLC* > J) 

specifies the volume(s) on which a cluster or 
alternate index is to reside, the volume on which a 
user catalog resides, or the volume(s) on which a 
non-VSAM data set resides. If entryname names a user 
catalog, you may specify only one volume serial number 
as a subparameter of VOLUMES. 

For a cluster or an alternate index, if VOLUMES is not 
coded, the original volume is the receiving volume. 

For a user catalog or a non-VSAM data set, if VOLUMES 
is not coded, the data set or user catalog must still 
reside on the same volume(s) as it did in the portable 
data set. 

When you specify VOLUMES for a cluster or alternate 
index, you can specify the cluster or alternate index 
name, the data component name or the index component 
name as entryname with the following results: 

• If VOLUMES is specified with the cluster or 
alternate index name, the specified volume list is 
defined for the data component. For a 
key-sequenced cluster or alternate index, the 
specified volume list is also defined for the 
index component. 

• If VOLUMES is specified with the data component 
name, the specified volume list is defined for the 
data component. Any specification of VOLUMES with 
the cluster or alternate index name is overridden. 

• For a key-sequenced cluster or alternate index, if 
VOLUMES is specified with the index component 
name, the specified volume list is defined for the 
index component. Any specification of VOLUMES 
with the cluster or alternate index name is 
overridden. 

For clusters or alternate indexes, if multiple volumes 
are specified, they must be of the same device type. 

By repeating the OBJECTS parameter set for each 
component and including VOLUMES in each parameter set, 
you can have the data and index components on 
different volumes. (See also the description of the 
FILE parameter.) 

Although the index and data components may reside on 
different device types, each volume of a multivolume 
component must be of the same type. 

Abbreviation: VOL 

OUTFILE(ddnaum) 

names the DD statement that contains a data set name and 
the volume serial number of each volume that is to contain 
the imported VSAM clusters and alternate indexes. You must 
use concatenated DD statements if the data sets are on 
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different device types. If the OUTFILE parameter is not 
supplied^ the required data sets are dynamically allocated 
as needed. 

The dsname specified with the DD statement cannot be one of 
the names cataloged in the target catalog (that is, the 
catalog that is to contain the imported catalog entries) 
and it cannot be one of the entrynames within the portable 
data set. 

■Cat a log..describes how this dsname is 
used by IMPORTRA processing. The DD statement(s) also 
specify the volume serial number(s), device type, DISP=0LD/ 
and AMP= 1 AMORG*. 

Abbreviation: OFILE 

SAVRACI NOSAVRAC 

specifies/ for a RACF-protected object/ whether existing 
profiles are to be used or whether new profiles are to be 
created. 

SAVRAC|NOSAVRAC applies to all VSAM components being 
imported back into the system. 

SAVRAC 

specifies that existing RACF data set profiles are to 
be saved and used/ rather than letting the system 
delete old profiles and create new default profiles. 
The profiles will actually be redefined by extracting 
information from existing profiles and adding caller 
attributes. You should ensure that these added 
attributes are acceptable. SAVRAC should be specified 
when RACF data set profiles already exist for objects 
being imported from the portable data set. 

The ownership creation group and access list will be 
altered by the caller of the SAVRAC option. 

Caution: You should ensure that valid profiles do 
exist for all components (for example/ cluster/ data/ 
index) being imported when SAVRAC is specified. If 
this is not done/ an invalid and possibly improper 
profile may be saved and used inappropriately. 

Remember that paths are imported with their 
corresponding cluster or alternate index/ and the same 
caution applies to these entries. In particular/ keep 
in mind that additional paths may be brought in during 
the import. 

NOSAVRAC 

specifies that a profile will be defined for the 
imported components if either the RACF Automatic Data 
Set Protection option has been specified for you or if 
the exported component had a RACF indication in the 
catalog at the time it was exported. NOSAVRAC should 
be specified when you wish new profiles to be created. 

There may be situations in which neither the SAVRAC nor 
NOSAVRAC mode would be suitable for all entities restored 
from the catalog recovery area. In such cases, the 
following procedure is suggested: 

• Issue two separate EXPORTRA commands/ resulting in two 
portable data sets. One EXPORTRA will create a 
portable data set containing entities to which SAVRAC 
should apply/ the other to which NOSAVRAC should apply. 

• Issue two IMPORTRA commands/ one specifying SAVRAC and 
the other NOSAVRAC. 
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IMPORTRA EXAMPLE 


This example shows how EXPORTRA and IMPORTRA can be used to 
recover a VSAM catalog. The first part illustrates the use of 
EXPORTRA. The second part shows how IMPORTRA is used. 


Recovering a VSAM Catalog: Example 1—Part 1 tEXPORTRA) 

This example performs the EXPORTRA function against the VSAM 
master catalog, AMASTCAT, and against all the volumes owned by 
it. All the data sets listed in the catalog recovery areas on 
the catalog volume and on the other volumes owned by AMASTCAT 
are exported to a SAM data set on another disk volume. Using 
the FORCE option causes EXPORTRA to ignore time stamp mismatches 
between the volumes and the catalog. 

//RECOVER JOB 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYSGUT=A 

//CRAV0L1 DD DISP=QLD,VOL=SER=VSER01,UNIT=DISK, 

// AMP= 1 AMORG 1 

//CRAV0L2 DD DISP=0LD,V0L=SER=VSERG4,UNIT=DISK, 

// AMP=’AMORG* 

//PORT DD DSNAME=PORT,DISP=CNEW,KEEP), 

// SPACE=(CYL,(3,3)),VOL=SER=231401, 

// UNIT=DISK,DCB=BLKSIZE=8000 

//SYSIN DD X 

EXPORTRA - 
CRAC - 

CCRAV0L1 ALL) - 
CCRAV0L2 ALL) - 
) - 

FORCE - 

OUTFILECPORT) - 
MASTERPW(MCATMRPW) 

/x 

Job control language statements: 

• CRAV0L1 DD, which identifies and allocates the first volume 
whose catalog recovery area contents is to be exported. 

• CRAV0L2 DD, which identifies and allocates the second volume 
whose catalog recovery area contents is to be exported. 

• PORT DD, which identifies the sequential file that is to 
receive the exported data sets and catalog recovery records. 
The DCB BLKSIZE parameter overrides the EXPORTRA default of 
2048 to improve performance. 

The EXPORTRA command exports everything appearing in the catalog 
recovery areas of volumes VSER01 and VSER04. The EXPORTRA 
command’s parameters are: 

• CRA, which is required and identifies the catalog recovery 
areas and volumes from which the export is to take place. 

The ddnames of the DD statements for these objects must be 
identical to the names specified for this parameter. The 
ALL subparameter specifies that everything is to be exported 
from each catalog recovery area. 

• FORCE, which specifies that timestamp mismatches are to be 
ignored. 

• OUTFILE, which is required and identifies the sequential 
(SAM) non-VSAM data set that is to receive the exported 
information. The ddname of the DD statement for this object 
must be identical to the name specified with this parameter. 

• MASTERPW, which specifies the master password of the master 
catalog. This parameter is required in order to export 
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information from catalog recovery areas controlled by a 
recoverable catalog. 


Recovering a VSAM Catalog: Example 1—Part 2 CIMPORTRA) 

This example imports all the data sets that were exported using 
EXPORTRA in the previous example. The receiving catalog is the 
VSAM master catalog/ and the CATALOG parameter is used to supply 
its master password. 

//RESTORE JOB 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT-A 

//PORT DD DSNAME=PORT/DISP=OLD/UNIT=DISK, 

// VOL=SER=333333/DCB=BLKSIZE=8GGO 

//VSAMIN DD DSNAME=DUMMY.NAME/DISP=OLD/UNIT=DSIK/ 

// V0L=SER = VSER01/AMP= 1 AMORG* 

// DD VOL=SER=VSER04/UNIT=DISK/DISP=OLD 

//SYSIN DD X 

IMPORTRA - 

INFILECPORT) - 
OUTFILECVSAMIN) - 
CATALOGCAMASTCAT/MCATMRPW) 

/x 

Job control language statements: 

• PORT DD/ which identifies and allocates the portable data 
set created previously by EXPORTRA. The DCB BLKSIZE 
parameter is included (even though it need not be/ because 
the information is contained in the DSCB for the data set) 
to illustrate the fact that the block size specified in the 
IMPORTRA job must be the same as that specified in the 
EXPORTRA job that created the portable data set. 

• VSAMIN DD/ which identifies and allocates the volumes of the 
objects to be imported. This permits them to be reloaded 
from the portable data set. The dsname appearing on the DD 
statement is required. It is a dummy name that must not 
appear either in the catalog or among the names on the 
portable data set. Because the volumes are of different 
device types/ concatenated DD statements must be used. 

The IMPORTRA command imports the data sets written on the 
portable data set by EXPORTRA previously. The IMPORTRA 
command^ parameters are: 

• INFILE/ which is required and which identifies the portable 
data set. 

• GUTFILE/ which identifies each VSAM volume involved in the 
import. The DD statement identified by OUTFILE also 
identifies the dummy data set/ DUMMY.NAME. 

• CATALOG/ which specifies the name of the master catalog. 

The master password of the target catalog is required in 
order to import catalog information. 



/f ' % 
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US.T.CM 

The LISTCAT command lists catalog entries. The format of this 
command is: 


LISTCAT 


FAI TSQI 

[ALTERNATEINDEX] 

[CLUSTER] 

[DATA! 

[GENERATIONDATAGROUP] 

[INDEX] 

[NONVSAN1 

[PAGESPACEl 

[PATH! 

[SPACE] 

[USERCATALOG] 

[CREATIONt davs )I 
[ ENTRIES C e ni r y,. n . a E 'Bas sm cd 3 
l mtrjyDM? e C 3 * «♦ 3) I 

LEVEL(JLev^l)3 
EEXPIRATION( davs )3 
C MAH S I 
HISTORY| 

VOLUME| 

ALLOCATION! 

ALL! 

CNOTUSABLE:] 

EOUTFILEC ddname )3 


ECATALOG(s.g tQaj ieE/pas ^ vyocd3 ) ] 


LISTCAT can be abbreviated: LISTC 


LISTCAT PARAMETERS 


Required Parameters 


The LISTCAT command has no required parameters. 

When the LISTCAT command is issued as a job step (that is, not 
through TSO) and no parameters are specified; an entire catalog 
is listed. See the section "Order of Catalog Search for 
LISTCAT" on page 18 for a description of how the catalog to be 
listed is selected. 

Note to TSO users: When LISTCAT is invoked from a TSO terminal 
and no operands are specified, the prefix of the TSO user 
becomes the highest level of entryname qualification and only 
those entries with a matching highest level of qualification are 
listed. It is as if you specified: 

LISTCAT LEVELETSO user prefix) 


Optional Parameters 


EALIAS3[ALTERNATEINDEX][CLUSTER][DATA] 

[GENERATIONDATAGROUP][INDEX]ENONVSAM] 

[PAGESPACElEPATH3[SPACE][USERCATALOG] 

specifies that certain types of entries are to be listed. 
Only those entries whose type is specified are listed. For 
example, when you specify CLUSTER but not DATA or INDEX, 
the clusters entry is listed and its associated data and 
index entries are not listed. 

When you specify ENTRIES and also specify an entry type, 
the entryname is not listed unless it is of the specified 
type. You can specify as many entry types as desired. 
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When you want to completely list a catalog, do not specify 
any entry type. 


ALXAS 


specifies that alias entries are to be listed. 


ALTERNATEINDEX 

specifies that entries for alternate indexes are to be 
listed. If ALTERNATEINDEX is specified and DATA and 
INDEX are not also specified, entries for the 
alternate index's data and index components are not 
listed. 


Abbreviations AIX 


CLUSTER 

specifies that cluster entries are to be listed. If 
CLUSTER is specified and DATA and INDEX are not also 
specified, entries for the cluster's data and index 
components are not listed. 

Abbreviations CL 




DATA 

specifies that entries for data components of clusters 
and alternate indexes are to be listed. 


If a VSAM object's name is specified and DATA is 
coded, only the object's data component entry is 
listed. When DATA is the only entry type parameter 
coded, the catalog's data component is not listed. 


GENERATIONBATAGROUP 

specifies that entries for generation data groups are 
to be listed. 


Abbreviations GDG 

INDEX 

specifies that entries for index components of 
key-sequenced clusters and alternate indexes are to be 
listed. If a VSAM object's name is specified and 
INDEX is coded, only the object's index component 
entry is listed. When INDEX is the only entry type 
parameter coded, the catalog's index component is not 
listed. 

Abbreviations IX 
NONVSAM 

specifies that entries for non-VSAM data sets are to 
be listed. If a generation data group's name and 
non-VSAM are specified, the generation data sets 
associated with the generation data group are listed. 

Abbreviations NVSAM 

PAGESPACE 

specifies that entries for page spaces are to be 
listed. 


Abbreviations PGSPC 

PATH 

specifies that entries for paths are to be listed. 


, 4 " "\ 
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SPACE 

specifies that entries for volumes containing data 
spaces defined in this catalog are to be listed. 
Candidate volumes are included. If entries are 
identified by entryname, SPACE can be coded only when 
no other entry type parameter is coded. 

Abbreviation: SPC 

USERCATALOG 

specifies that catalog connectors are to be listed. 

The user catalog connector entries are in the master 
catalog. (User catalog connector entries can also be 
in a user catalog, but the operating system does not 
recognize them when searching for a user catalog.) 

Abbreviation: UCAT 

CATALOGC catname [/ Password !) 

specifies the name of the catalog that contains the entries 
that are to be listed. If CATALOG is coded, only entries 
from that catalog are listed. See "Order of Catalog Search 
for LISTCAT" on page 18 for information about the order in 
which catalogs are searched. 

ca.tn.Me 

is the name of the catalog. 

E3^word 

specifies the read- or higher-level password of the 
catalog that contains entries to be listed. RACF: The 
read or higher RACF authority to the catalog is 
required. If the entries to be listed are password 
protected, a password must be supplied either through 
this parameter or through the ENTRIES parameter. If 
passwords are to be listed, you must specify the 
master password. RACF: The alter RACF authority to 
the catalog is required. 

If the catalog f s volume is physically mounted, it is 
dynamically allocated. The volume must be mounted as 
permanently resident or reserved. 

Abbreviation: CAT 

CREATION( davs ) 

specifies that entries of the indicated type, such as 
CLUSTER and DATA, are to be listed only if they were 
created the specified number of days ago or earlier. 

days. 

specifies the number of days ago. This value can be 
expressed in decimal, hexadecimal, or binary. If it 
is expressed in either hexadecimal or binary, it must 
be preceded by either f X f or l B l and be enclosed in 
single quotation marks. 

The maximum number that can be specified is 9999; zero 
indicates that all entries are to be listed. 

Abbreviation: CREAT 

entries ( Gixkr.'mm& C / PMsw End 3I ani ry-Qamjs l 3 •••3)1 

LEVEL tlgyel) 

specifies the names of entries to be listed. 

Entries are only listed from an OS CVOL if the ENTRIES or 
LEVELS parameter is specified and: 

• The CATALOG parameter is not specified. 

• No JOBCAT or STEPCAT DD is specified. 
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• The highei—level qualifier of the name specified using 
ENTRIES or LEVELS is the alias of the OS CVOL. 

When a LISTCAT LEVEL of a CVOL is made, a maximum of 1456 
entries can be listed. 

Note to TSO users: TSO will prefix the userid to the 
specified data set name when the ENTRIES parameter is 
unqualified. The userid is not prefixed when the LEVEL 
parameter is specified. 


CjUX t cm a me l / pa s s word 3 «**3 3 

specifies the name or generic name of each entry to be 
listed. (See the generic examples following the 
description of the LEVEL parameter.) When you want to 
list the entries that describe a user catalog, the 
catalog's volume must be physically mounted. You then 
specify the catalog's name as the entryname. If you 
want data space information, you must specify the 
volume serial number (as the entryname) of the volume 
containing the data space; you must also specify SPACE 
and no other entry type parameters. 

B& gs m i L d 

specifies a password when the entry to be listed 
is password protected and a password is not 
specified with the CATALOG parameter. The 
password can be any of the entry's passwords. 

The entry's protection attributes are listed only 
when you specify the entry's (or its catalog's) 
master password. RACFs The alter RACF authority 
to the catalog or entry is required. 

When you don't supply a password for a 
password-protected entry, the operator or TSO 
terminal user is prompted for the entry's 
password. You cannot supply a password for these 
types of entries: non-VSAM data set, generation 
data group, alias, user catalog connector, or 
data space. 

Abbreviation: ENT 

LEVEL (l^vel.) 

specifies that all entries that match the level of 
qualification specified by (level) are to be listed, 
irrespective of the number of additional qualifiers. 

If a generic level name is specified, only one 
qualifier replaces the X. The X must not be the last 
character specified in the LEVEL parameter. 

LEVEL(A.x) will give you an error message. 

Abbreviation: LVL 


&£3inpl^ s _ojL.^^ f i.gat i Q.ns * Suppose a 

catalog contains the following names: 

1. A.A.B 

2. A.B.B 

3. A.B.B.C 

4. A.B.B.C.C 

5. A.C.C 

6. A.D 

7. A.E 

8. A 
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If ENTRIES(A.X) is specified/ entries 6 and 7 will be 
listed. If ENTRIESCA.*.B) is specified/ entries 1 and 2 
will be listed. If LEVEL(A.*.B) is specified/ entries 1/ 

2/ 3, and 4 will be listed. If LEVELCA) is specified/ 
entries 1/ 2/ 3/ 4/ 5/ 6, and 7 will be listed. 

When using a generic name with the ENTRIES parameter/ 
entries must have one qualifier in addition to those 
specified in the command. 

EXPIRATION ( davs ) 

specifies that entries of the indicated type/ such as 
CLUSTER and DATA/ are to be listed only if they will expire 
in the specified number of days or earlier. 

.days 

specifies the number of days. This value can be 
expressed in decimal/ hexadecimal/ or binary. If it 
is expressed in either hexadecimal or binary/ it must 
be preceded by either i X f or 'I* 1 and be enclosed in 
single quotation marks. The maximum number that can 
be specified is 9999 and indicates that all entries 
are to be listed. Any value that exceeds the year 
2000 will default to 99.999(yyddd). Zero indicates 
that only entries that have already expired are to be 
listed. 

Abbreviation: EXPIR 

NAME I HISTORY|VOLUME|ALLOCATION|ALL 

specifies the fields to be included for each entry listed. 
Appendix A/ "Interpreting LISTCAT Output Listings" on 
page 256/ shows the listed information that results when 
you specify nothing (which defaults to NAME)/ HISTORY/ 
VOLUME/ ALLOCATION/ and ALL. 

NAME 

specifies that the name and entry type of the entries 
are to be listed. 

Some entry types are listed along with their 
associated entries. The entry type and name of the 
associated entry follow the listed entry’s name. For 
details/ see "ASN: Associations Group" in 
Appendix A/ "Interpreting LISTCAT Output Listings" on 
page 256. 

Note to TSO users: Only the name of each entry 
associated with the TSO user*s prefix is listed when 
no other parameters are coded. 

HISTORY 

specifies that only the following information is to be 
listed for each entry: name/ entry type/ ownerid/ 
creation date/ expiration date/ and for a recoverable 
catalog’s entries/ the catalog recovery area’s volume/ 
device type/ and control interval number. It can be 
specified for CLUSTER/ DATA/ INDEX, ALTERNATEINDEX, 
PATH, GENERATIONDATAGRGUP, PAGESPACE, and NONVSAM. 

Abbreviation: HIST 

VOLUME 

specifies that the information provided by specifying 
HISTORY plus the volume serial numbers and device 
types allocated to the entries, are to be listed. 
Volume information is only listed for data and index 
component entries, data space (volume) entries, 
non-VSAM data set entries, and user catalog connector 
entries. 

Note to TSO users: Only the name and volume serial 
numbers associated with the TSO user’s prefix are 
listed when no other parameters are coded. 
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Abbreviation: VOL 
ALLOCATION 

specifies that the information provided by specifying 
VOLUME plus detailed information about the allocation 
are to be listed. The information about allocation is 
listed only for data and index component entries. 

Abbreviation: ALLOC 


ALL 

specifies that all fields are to be listed. 

NOTUSABLE 

specifies that only those data and index entries with the 
"unusable 11 indicator on are to be listed. A data or index 
component is marked "unusable” when a system failure occurs 
that results in damage to the entry*s cataloged 
information. 

When the cataloged information is reset/ the damaged entry 
and its backup copy (in the catalog recovery area) might 
not match when the space allocation information is 
compared. VSAM marks the catalog entry "unusable" until 
the space allocation information is corrected. See Catalog 

for more details. 

Abbreviation: NUS 

ouTFiLEt dd pa me ) 

specifies a data set/ other than the SYSPRINT data set/ to 
receive the output produced by LISTCAT (that is> the listed 
catalog entries). Completion messages produced by access 
method services are sent to the SYSPRINT data set/ along 
with your job's JCL and input statements. 

ddname identifies a DD statement that describes the 
alternate target data set. If OUTFILE is not specified/ 
the entries are listed in the SYSPRINT data set. If an 
alternate data set is specified/ it must meet the 
requirements in "For an Alternate Target Data Set" on 
page 10. 

Abbreviation: OFILE 
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LZSTCAT EXAMPLES 


Listing a Key-Sequenced Cluster’s Entry in a Catalog: Example 1 

In this example, a key-sequenced cluster entry is listed. 

//LISTCAT1 JOB 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYS0UT=A 

//SYSIN DD X 

LISTCAT - 

ENTRIESCD4Q.EXAMPLE.KSDS1) - 
CLUSTER - 
ALL 
/x 

The LISTCAT command lists the cluster’s catalog entry. It is 
assumed that the high level of the qualified cluster name is the 
same as the alias of the catalog D27UCAT1; this naming 
convention directs the catalog search to the appropriate 
catalog. Its parameters are: 

• ENTRIES, which identifies the entry to be listed. 

• CLUSTER, which specifies that only the cluster entry is to 
be listed. If CLUSTER had not been specified, the cluster’s 
data and index entries would also be listed. 

• ALL, which specifies that all fields of the cluster entry 
are to be listed. 


Alter a Catalog Entry, Then List the Modified Entry: Example 2 

In this example, the free space attributes for the data 
component (KSDATA) of cluster MYDATA are modified. Next, the 
cluster entry, data entry, and index entry of MYDATA are listed 
to determine the effect, if any, the modification has on the 
cluster’s other attributes and specifications. 

//LISTCAT2 JOB 

//J0BCAT DD DSNAME=D27UCAT1,DISP=SHR 

//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=A 

//SYSIN DD X 

ALTER - 

D40.KSDATA - 
FREESPACEC10 10) 

IF LASTCC = 0 - 
THEN - 
LISTCAT - 

ENTRIESCD40.MYDATA) - 
ALL 
/x 

Job control language statement: 

• JOBCAT DD, which makes a catalog available for this job: 
D27UCAT1. 

The ALTER command modifies the free space specifications of the 
key-sequenced VSAM cluster D40.MYDATA. The command’s parameters 
are: 

• D40.KSDATA, which is the entryname of the data component 
being altered. D40.KSDATA identifies the data component of 
a key-sequenced VSAM cluster, D40.MYDATA. In order to alter 
a value that applies only to the cluster’s data component, 
such as FREESPACE does, you must specify the data 
component’s entryname. 
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• FREESPACE/ which specifies the new free space percentages 

for the data components control intervals and control ff 

areas. L 

The IF ... THEN command sequence verifies that the ALTER command 
completed successfully before the LISTCAT command executes. 

The LISTCAT command lists the cluster's entry and its data and 
index entries. Its parameters ares 

• ENTRIES/ which specifies the entryname of the object being 
listed. Because D40.MYDATA is a key-sequenced cluster/ the 
cluster entry/ its data entry/ and its index entry are 
listed. 

• ALL/ which specifies that all fields of each entry are to be 
listed. 


List Catalog Entries: Example 3 

This example illustrates how all catalog entries with the same 
generic name are listed. 

//LISTCAT3 JOB 

//JOBCAT DD DSNAME=USERCAT4/DISP=SHR 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYS0UT=A 

//SYSIN DD X 

LISTCAT - 

ENTRIESCGENERIC.X.BAKER) - 
ALL 


Job control language statement: 

• JOBCAT DD/ which makes a catalog available for this job: 
USERCAT4. 

The LISTCAT command lists each catalog entry with the generic 
name GENERIC.X.BAKER/ where "X" is any 1- to 8-character simple 
name. Its parameters are: 

• ENTRIES/ which specifies the entryname of the object to be 
listed. Because GENERIC.X.BAKER is a generic name/ more 
than one entry might be listed. 

• ALL/ which specifies that all fields of each entry are to be 
listed. 
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U.5IQBA 


The LISTCRA command lists or compares the contents of a given 
catalog recovery area (CRA). This command is for use with 

The format of the LISTCRA command is: 


LISTCRA 

INFILE (ridnanet ddname• ♦ •)) 


tCATALOGCcatnamet/password] ddname)] 


[ COMPARE 1 NOCOMPARE] 


[DUMP I NAME|SEQUENTIALDUMP1 


IMASTERPWtpassword)] 


COUTFILEl ddname)] 


LISTCRA can be abbreviated: LISTR 


LISTCRA PARAMETERS 


Required Parameters 


INF!LE(ddnanifiE ddoamg**»3) 

identifies the DD statement(s) that describes the catalog 
recovery area f s volume. You can list or compare more than 
one catalog recovery area. However, if COMPARE is 
specified, all volumes whose catalog recovery areas are 
listed must be owned by the same VSAM catalog. 

Note: The ddname list for the INFILE parameter is limited 

to 9 ddnames. 


Optional Parameters 


CATALOG t sal a ams t /B ass m r d 3 d dn a me * 

identifies the catalog that owns the volume(s) identified 
with the INFILE parameter. The CATALOG parameter is 
required when you specify the COMPARE option either with 
the DUMP or NAME output format. CATALOG cannot be 
specified with SEQUENTIALDUMP. 

ga£SHQ £ d 

When the catalog is password protected, you must 
supply the catalog f s master password. The password is 
required, even though the master catalog's password 
may have been supplied in the MASTERPW parameter. 

RACF: The alter RACF authority to the catalog is 
required. 


When CATALOG is specified, you must describe and 
allocate the catalog to be compared with a DD 
statement. ddname identifies the catalog's DD 
statement, and is required when you specify the 
CATALOG parameter. You cannot specify JOBCAT or 
STEPCAT as the ddname. However, if the catalog being 
compared is not the VSAM master catalog, you must also 
identify the catalog by a STEPCAT or JOBCAT DD 
statement in addition to the DD statement referenced 
by ddname. 

If the catalog information is entered incorrectly, the 
NOCOMPARE default is taken, and all the CRA records are 
listed. 

Abbreviation: CAT 
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COMPARE IMafiSMEMS 

specifies whether the list is to be limited to those 

entries in the catalog recovery area that do not match L 

their corresponding catalog entries. > 

COMPARE 

When you specify COMPARE, only those entries that do 
not match are listed. All the catalog f s entries are 
compared, except the catalog's self-describing 
records. You must identify the catalog (that contains 
the catalog entries that are still to be compared) 
with the CATALOG parameter. 

The COMPARE parameter cannot be specified if you 
specify SEQUENTIALDUMP. 

Note: If you specify the COMPARE option, page space 

entries will always result in a mismatch. This is a 
normal condition and does not require any corrective 
action. The mismatch is caused by the OPEN indicator 
not being set in the page space record in the CRA, 
whereas it is set in the catalog. 

Abbreviation: CMPR 

NOCOMPARE 

When you specify NOCOMPARE (or allow it to default), 
all the catalog recovery area's records are listed. 

Abbreviation: NCMPR 

See Appendix B, "Interpreting LISTCRA Output Listings" on 
page 301 for examples of each type of output listing. 

DUMP| NAME |SEQUENTIALDUMP 

specifies the amount of cataloged information to be listed. 

DUMP 

specifies that each listed entry is printed in its 
entirety in both hexadecimal and character form. 

Records are listed alphamerically and grouped by 
components. 


NAME 

specifies that each listed entry includes only the 
entry's name, its volume serial numbers, and the name 
and entry type of each associated entry. All listed 
entries are sorted alphamerically and grouped. 

SEQUENTIALDUMP 

specifies that each listed entry is to be printed in 
its entirety in both hexadecimal and character form. 
Records are listed in the sequence in which they 
appear in the catalog recovery area. 

Abbreviation: SDUMP 

The DUMP, NAME, SEQUENTIALDUMP, COMPARE, and NOCOMPARE 
options can be specified to produce five different kinds of 
output listing. See Appendix B, "Interpreting LISTCRA 
Output Listings" on page 301, for examples of each type of 
listing. 

MASTERPW(p.^swpxd) 

specifies the master catalog's master password. This 
parameter is required when the master catalog is 
password-protected. 

Abbreviation: MRPW 
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OUTFlLECddnan^) 

identifies the DD statement that describes an alternate 
target data set. See "For an Alternate Target Data Set 11 on 
page 10 for more details about alternate target data sets. 

When OUTFILE is not specified, the listing is printed on 
the output device described with the SYSPRINT DD statement. 
When OUTFILE is specified, the listing produced by LISTCRA 
is sent to the alternate target data set; the remainder of 
the access method services output is printed on the output 
device described with the SYSPRINT DD statement. Refer to 
Appendix B, "Interpreting LISTCRA Output Listings” on 
page 301, for an example of the use of the OUTFILE 
parameter. 

Abb reviation: 0 FIL E 
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LXSTCRA EXAMPLE 

/€ 


Listing a Catalog Recovery Area: Example 1 

This example lists in dump format the catalog recovery areas for 
those volumes owned by the VSAM master catalog, AMASTCAT, and 
compares those catalog recovery areas with the actual catalog 
records themselves. 

//LISTAREA JOB 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYS0UT=A 

//CRAV0L1 DD DISP=QLD,VQL=SER=SG20Q1,UNIT=DISK 

//CRAVQL2 DD DISP=0LD,VQL=SER=VSER04,UNIT=DISK 

//CATVOL DD DSNAME=AMASTCAT,DISP=0LD 
//SYSIN DD X 

LISTCRA - 

INFILEC - 
CRAV0L1 - 
CRAV0L2) - 

MASTERPW(MCATMRPW) - 
COMPARE - 
DUMP ~ 

CATALOGCAMASTCAT/MCATMRPN CATVOL) 

/x 

Job control language statements: 

• CRAV0L1 DD, which identifies and allocates the volume that 
contains the first catalog recovery area to be listed. 

• CRAV0L2 DD, which identifies and allocates the volume that 
contains the second catalog recovery area to be listed. 

• CATVOL DD, which identifies and allocates the catalog to be 
compared against, and makes the catalog available to LISTCRA 
as a data set. Because this example is listing the master 
catalog, no STEPCAT or JOBCAT DD statement is required. 

However, if the example were listing a user catalog, a 
STEPCAT or JOBCAT DD statement would be required in addition 
to the CATVOL DD statement to describe the user catalog as a 
catalog. 

The LISTCRA command causes the catalog recovery areas on volumes 
SG2001 and VSER04 to be listed and their contents compared with 
the VSAM system catalog AMASTCAT. The LISTCRA command's 
parameters are: 

• INFILE, which is required and specifies the catalog recovery 
areas to be listed by identifying the DD statement that 
describes each CRA's volume. 

• MASTERPW, which specifies the master password of the master 
catalog. This parameter is required in order to open the 
catalog recovery areas for LISTCRA processing. 

• COMPARE, which specifies that the catalog records are to be 
compared with their copies in the catalog recovery areas. 

• DUMP, which specifies that the results of the record 
comparison (that is, the LISTCRA output listing) are to be 
printed in dump format. 

• CATALOG, which is required because the COMPARE option was 
specified. This parameter identifies the catalog to be 
compared against by identifying the DD statement that 
describes and allocates the catalog as a data set. 

4 
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PJBIIil 

The PRINT command prints VSAM data sets# non-VSAM data sets# and 
catalogs. The format of this command is: 


PRINT 


{INFILE ! ridg ams c te s s su &juA 3) I 
INDATASET ! . er i t r y najne E/ pa , s . sw .p.r.d 3 
ICHARACTER I DUMP I HEX1 
l FROMKEY(key)|FROMADDRESS C address )| 
FROMNUMBER ( mmk&r .) 1 SKIP (number) 3 
[QUTFILEIdri M jnfill 
CTQKEYCkev)1TQADDRESSC address )| 
TONUMBERt number )1 COUNT! number )3 


PRINT PARAMETERS 


Required Parameters 


INFILE!driaamsE/RassMacd3J1 
INDAT ASET! E / B a s s MffiCjd 3 3 

identifies the data set or component to be printed. If the 
logical record length of a non-VSAM source data set is 
greater than 32760 bytes# your PRINT command will terminate 
with an error message. 

infile! .ddnamfi E /mssm r .d 3) 

specifies the name of the DD statement that identifies 
the data set or component to be printed. 

You can list a base cluster in alternate-key sequence 
by specifying a path name as the data set name in the 
DD statement. 

Abbreviation: I FIL E 

INDATASET! entrvname t /password ]) 

specifies the name of the data set or component to be 
printed. If INDATASET is specified# the entryname is 
dynamically allocated. 

You can list a base cluster in alternate-key sequence 
by specifying a path name as entryname. 

Bassmrsl 

If a VSAM data set or component is password 
protected# a password must be supplied. The 
password to be supplied is: 

• The master password of the catalog if you are 
listing a catalog. RACF: The alter RACF 
authority to the catalog is required. 

• The read- or highei—level password of the 
data set or component if the data set or 
component is not a catalog. RACF: The read 
or higher RACF authority to the data set or 
component is required. 

• The master password of the cluster if you are 
listing a component of a password-protected 
cluster. RACF*. The alter RACF authority to 
the cluster is required. 

Passwords are applicable only to VSAM data sets and 
their components. 

Abbreviation: IDS 
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Optional Parameters 


CHARACTERI DUMP I HEX 

specifies the format of the listing. 

CHARACTER 

specifies that each byte in the logical record is to 
be printed as a character. Bit patterns not defining 
a character are printed as periods. Key fields are 
listed in character format (see Figure 4). 

Abbreviation: CHAR 


XOCAffS SYSTEM SERVICES TIME: 19:26:13 03/06/75 PA6E 6 


IISTINS OP OATA SET -EXAMPLE.LISTC.DATA 
R0A OF RECORD - 0 

A6CO000000000001ABCOEF6HIJKLMNOPQRSTUV)4XYZ0123456769ABC0EFGHUKlMNOPQRSTUVWXYZ0123456769A6COEFGHXJKLMNOPQR3TUVMXYZ01234S 
6769ABCDEFGMUKLMNOPQRSTUVWXYZ0123456769ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABC0EFGHUKLKNOPqR3TUVKXYZ0123456769ABCDEFGM 
UKLMNOPQR3TUVWXYZ0123456769A6COEFGHIJKLMNOPQPSTUVMZYZ0123456 789ABCOEFGHIJKU1MOPQRSTUVMXYZOl234567d9ABCOEFGHUKLMNOPQRST 
UVIOCYZ0123456769ABCOEFGHIJKLMNOPQR3T.... 

Figure 4. Example of Character Format of PRINT Command 


DUMP 

specifies that each byte in the logical record is to 
be printed in both hexadecimal and character format. 
In the character portion of the listing, bit patterns 
not defining a character are printed as periods. Key 
fields are listed in hexadecimal format (see 
Figure 5). 


IDCAM3 SYSTEM SERVICES 


TIME: 19:25:14 03/06/75 PAGE 2 


LISTING OF OATA SET -EXAMPLE.LISTC 


KEY OF RECORO - F0F0F0F0F0F0F0F0F0F0F0F1 
0006 C1C2C3C4 F0F0F0F0 F0F0F0F0 F0F0F0F1 

0020 9009E2E3 E4E5E6E7 E6E9F0F1 F2F3F4F5 

0040 04050607 0609E2E3 E4E5E6E7 F6F9F0F1 

0060 C9010203 04050607 D6D9E2E3 E4E5E6E7 

0060 C5C6C7C6 C9010203 04050607 0609E2E3 

00A0 CIC2C3C4 C5C6C7C6 C9010203 04050607 

00C0 F6F7F6F9 C1C2C3C4 C5C6C7C6 C9010203 

00E0 F2F3F4F5 F6F7F6F9 C1C2C3C4 C5C6C7C6 

0100 E6E9F0F1 F2F3F4F5 F6F7F6F9 C1C2C3C4 

0120 E4ESE6E7 E6E9F0F1 F2F3F4F5 F6F7F6F9 

0140 0609E2E3 E4E5E6E7 E6E9F0F1 F2F3F4F5 

0160 04050607 0609E2E3 E4E5E6E7 E6E9F0F1\ 

0160 C9010203 04050607 0609E2E3 00000000 


C1C2C3C4 C5C6C7C6 
F6F7F6F9 C1C2C3C4 
F2F3F4F5 F6F7F8F9 
E6E9F0F1 F2F3F4F5 
E4E5E6E7 E8E9F0F1 
D809E2E3 E4E5E6E7 
D405D6D7 D809E2E3 
C9010203 D4D506D7 
C5C6C7C6 C9010203 
C1C2C3C4 C5C6C7C6 
F6F7F8F9 C1C2C3C4 
F2F3F4F5 F6F7F6F9 


C9010203 04050607 
C5C6C7C8 C9010203 
C1C2C3C4 C5C6C7C8 
F6F7F8F9 C1C2C3C4 
F2F3F4F5 F6F7F8F9 
E6E9F0F1 F2F3F4F5 
E4E5E6E7 E8E9F0F1 
D8D9E2E3 E4E5E6E7 
04050607 0609E2E3 
C9010203 04050607 
C5C6C7C6 C9010203 
C1C2C3C4 C5C6C7C6 


Figure 5. Example of Dump Format of PRINT Command 


•ABCOOOOOOOOOOOOIABCDEFGNUKLMNOP* 
•QRSTUVWXYZO123456769A6CDEF6HIJKL* 
•Mf JOPQRSTUVWXYZO12 3456769ABC0EF6H* 
•IJK LMNOPQRSTUVWXYZO123456769ABC0* 
•E FCHIJK LMNOPQRSTUVWXYZO123456789* 
•ABCOEFGHIJKLMNOFQRSTUVMXYZO12345» 
•6789ABC0 E F GHIJK LMNOPQRSTUVWXYZO1* 
•23456789ABC0EFGHUK LMNOPQRSTUVMX* 
•YZO123456769A8CDEFGHIJKLMNOPQRST* 
•UVWXYZO123456769ABC0EFGHIJKLMN0P4 
•QRSTUVMXYZO123456 769A6C0EFGHIJKL« 
•MNOPQRSTUVWXYZO123456769ABC0EFGH* 
•IJKLMNOPQRST...• * 


HEX 

specifies that each byte in the logical record is to 
be printed as two hexadecimal digits. Key fields are 
listed in hexadecimal format (see Figure 6 on 
page 219), 


yf . 
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XDCANS SYSTEM SERVICES 


TIME: 19:26:13 03/08/75 PAGE 4 


LISTING OF DATA SET -EXAMPLE.LISTC.DATA 
RBA OF RECORO - 0 

C1C2C3C4F0F0F0F0F0F0F0F0F0F0F0F1C1C2C3C4C5C6C7C8C9D102D3D4D5D6D7D8D9E2E3E4E5E6E7E8E9F0F1F2F3F4F5F6F7F8F9C1C2C3C4C5C6C7C8 

C90ID20304D50607D809E20304E5E6E7E8E9FOFIF2F3F4F5F6F7F8F9C1C2C3C4C5C6C7C8C9D1D203D4D5D6D7D8D9E2E3E4E5E6E7E8E9FOF1F2F3F4F5 

F6F7F6F9C1C2C3C4C5C6C7C8C9D1D2D304D5D6D708D9E2E3E4E5E6E7E8E9F0F1F2F3F4F5F6F7F8F9C1C2C3C4C5C6C7C8C9D1D2D3D4D5D6D7D8D9E2E3 

E4E5E6E7E8E9F0F1F2F3F4F5F6F7F8F9C1C2C3C4C5C6C7C8C9D1D2D3D4D5D6D7D8D9E2E3E4E5E6E7E8E9F0F1F2F3F4F5F6F7F8F9C1C2C3C4C5C6C7C8 

C9010203040506070809E2E3E4E5E6E7E8E9FOF1F2F3F4F5F6F7F8F9C1C2C3C4C5C6C7C8C9D1D2D3D4D5D6D7D8D9E2E3E4E5E6E7E8E9FOFIF2F3F4F5 

F6F7F8F9C1C2C3C4C5C6C7C8C9D102D3D4D5D6D7D8D9E2E3E4E5E6E7E8E9FOFIF2F3F4F5F6F7F8F9C1C2C3C4C5C6C7C8C901D2D3D4050607D809E2E3 

E4E5E6E7E6E9FOFlF2F3F4F5f6F7F6F9ClC2C3C4C5C6C7C8C9010203D40506070809E2E300000000 

Figure 6. Example of Hexadecimal Format of PRINT Command 


FROMKEYCkysy) IFROMADDRESSladdress) I 
FRommBERijms^USKiPirnrnhMxil 

specifies the location in the data set being listed from 
which listing is to start. If you do not specify a value, 
the listing begins with the first logical record in the 
data set or component. The only value that can be 
specified for a SAM data set is SKIP. 

The starting delimiter must be consistent with the ending 
delimiter. For example, if FROMADDRESS is specified for 
the starting location, use TOADDRESS to specify the ending 
location. The same is true for FROMKEY and TOKEY, and 
FROMNUMBER and TONUMBER. 

FRQMKEY(kev) 

specifies the key of the first record you want listed. 
You can specify generic keys (that is, a portion of 
the key followed by X). If you specify generic keys, 
listing begins at the first record whose key matches 
that portion of the key you specified. 

You cannot specify a key longer than that defined for 
the data set. If you do, the listing is not 
performed. If the specified key is not found, the 
next higher key is used as the starting point for the 
listing. 

FROMKEY can be specified only when an alternate index, 
a key-sequenced VSAM data set, a catalog, or an 
indexed sequential (ISAM) non-VSAM data set is being 
printed. 

kev 

can contain 1 to 255 EBCDIC characters. 

Abbreviation: FK EY 

FROMADDRESS( aridCfiSS) 

specifies the relative byte address (RBA) of the first 
record you want listed. The RBA value must be the 
beginning of a logical record. If you specify this 
parameter for a key-sequenced data set, the listing 
will be in physical sequential order instead of in 
logical sequential order. 

FROMADDRESS can be specified only for VSAM 
key-sequenced or entry-sequenced data sets or 
components. FROMADDRESS cannot be specified when the 
data set is accessed through a path or for a 
key-sequenced data set with spanned records if any of 
those spanned records are to be accessed. 

Abbreviation: FADDR 
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FROMNUMBERC number ) 

specifies the relative record number of the first 
record you want printed. FROMNUMBER can only be 
specified for VSAM relative record data sets. 

Abbreviation: FNUM 

SKlPCjoumben) 

specifies the number of logical records you want to 
skip before the listing of records begins. For 
example, if you want the listing to begin with record 
number 500/ you specify SKIP(499). SKIP should not be 
specified when you are accessing the data set through 
a path; the results are unpredictable. 

m b Q .r 

can be expressed in decimal (n)# hexadecimal (X'n 1 )# 
or binary The expression cannot be longer 

than one fullword (8 decimal or hexadecimal numbers# 
or 32 binary numbers). 

OUTFlLEtdd ra mel 

identifies a target data set other than SYSPRINT. For 
ddname/ substitute the name of the JCL statement that 
identifies the alternate target data set. 

The access method services target data set for listings/ 
which is identified by the ddname SYSPRINT/ is the default. 
The target data set must meet the requirements stated in 
"For a Target Data Set" on page 10. 

Abbreviation: OFILE 

TOKEYlkey ) iTOADDRESS(addnsgs) I 
TONUMBER ( numbs.L 31 COUNT (nymtoJC ) 

specifies the location in the data set being listed at 
which you want the listing to stop. If no value is 
specified/ the listing ends with the logical end of the 
data set or component. The only value that can be 
specified for a SAM data set is COUNT. The location at 
which the listing is to stop must follow the location at 
which the listing is to begin. 

The ending delimiter must be consistent with the starting 
delimiter. For example/ if FROMADDRESS is specified for 
the starting location/ use TOADDRESS to specify the ending 
location. The same is true for FROMKEY and TOKEY/ and 
FROMNUMBER and TONUMBER. 

TOKEYCkev) 

specifies the key of the last record to be listed. 

You can specify generic keys (that is/ a portion of 
the key followed by X) . If you specify generic keys/ 
listing stops after the last record is listed whose 
key matches that portion of the key you specified. If 
you specify a key longer than that defined for the 
data set/ the listing is not performed. 

If the specified key is not found/ the next lower key 
is used as the stopping point for the listing. 

TOKEY can be specified only when an alternate index# a 
key-sequenced VSAM data set# a catalog# or an indexed 
sequential (ISAM) non-VSAM data set is being printed. 

&£Y 

can contain 1 to 255 EBCDIC characters. 
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TOADDRESS ( address ) 

specifies the relative byte address (RBA) of the last 
record you want listed. 

Unlike FROMADDRESS, the RBA value does not need to be 
the beginning of a logical record. The entire record 
containing the specified RBA is printed. If you 
specify this parameter for a key-sequenced data set, 
the listing will be in physical sequential order 
instead of in logical sequential order. 

TOADDRESS can be specified only for VSAM key-sequenced 
or entry-sequenced data sets or components. TOADDRESS 
cannot be specified when the data set is accessed 
through a path. TOADDRESS cannot be specified for a 
key-sequenced data set with spanned records if any of 
those spanned records are to be accessed. 

Abbreviation: TADDR 

TONUHBERCnymb&r.) 

specifies the relative record number of the last 
record you want printed. TQNUMBER can only be 
specified for a VSAM relative record data set. 

Abbreviation: TNUM 

COUNTCgymhflEl 

specifies the number of logical records to be listed. 
COUNT should not be specified when you are accessing 
the data set through a path; the results are 
unpredictable. 

can be expressed in decimal (n), hexadecimal (X 1 ^), 
or binary (B f n*); the expression cannot be longer than 
one fullword (8 decimal or hexadecimal numbers, or 32 
binary numbers). 
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PRINT EXAMPLES 


Print a Catalog: Example 1 

This example shows how to print a catalog. You may find this 
function of the PRINT command helpful in the event of a problem 
with your catalog. 

//PRINT3 JOB ... 

//JOBCAT DD DSNAME=USERCAT4,DISP=0LD 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYS0UT=A 

//SYSIN DD X 

/X PRINT THE ENTIRE CATALOG X/ 

PRINT - 

INDATASETCUSERCAT4) 

/x 

Job control language statement! 

• JOBCAT DD, which is required and which describes and 
allocates the user catalog to be printed. 

The PRINT command prints the entire catalog, because there are 
no delimiting parameters specified. 


Print a Catalog: Example 2 

This example shows various ways to print a catalog. You may 
find this function of the PRINT command helpful in the event of 
a problem with your catalog. 

//PRINT3 JOB ... 

//JOBCAT DD DSNAME=D27UCAT1,DISP=0LD 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYS0UT=A 

//SYSIN DD X 

/X PRINT THE LOW KEY RANGE OF THE CATALOG X/ 

PRINT - 

INDATASET(D27UCAT1) - 
TOKEY (X*3F') 

/X PRINT THE HIGH KEY RANGE OF THE CATALOG x/ 

PRINT - 

INDATASETC D27 UCAT1) - 
FROMKEY (X'^O*) 

/X PRINT A SPECIFIC RECORD X/ 

/X FROM THE LOW KEY RANGE X/ 

PRINT - 

INDATASET(D27UCAT1) - 
FROMKEY (X'OOOOOOOE*) - 
COUNT (1) 

/X PRINT THE ENTIRE CATALOG x/ 

PRINT - 

INDATASETCD27UCAT1) 

/X 

The job control language statements ares 

• JOBCAT DD, which is required and which describes and 
allocates the user catalog to be printed. 

The first PRINT command prints the low-key range of the catalog. 
Its parameters ares 

• INDATASET, which specifies the name of the catalog to be 
printed. 
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• TOKEY, which specifies that printing is to terminate after 
reaching a record whose key is greater than X*3F f (in its 
first byte). The low-key range of a VSAM catalog contains 
records with a range of keys having a value from X’OO’ to 
X’3F’ in the first byte. 

The second PRINT command prints the high-key range of the 

catalog. Its parameters are: 

• INDATASET, which specifies the name of the catalog to be 
printed. 

• FROMKEY, which specifies that printing is to begin at the 
first record whose key is X^O* or greater (in its first 
byte). The high-key range of a VSAM catalog contains 
records with a range of keys having a value from X f 40 f to 
X’FF’ in the first byte. 

The third PRINT command prints one catalog record from the 

low-key range of the catalog. Its parameters are: 

• INDATASET, which specifies the name of the catalog to be 
printed. 

• FROMKEY, which specifies that printing is to begin with the 
record whose key is X’OOOOOOGE 1 in the first 4 bytes. 
Records in the low-key range of a VSAM catalog have the 
number of the containing control interval as the first 4 
bytes of their key. Records are 505 bytes in length and 
each record is contained in a 512-byte control interval. 

• COUNT, which specifies that only one record is to be 
printed. 

The fourth PRINT command prints the entire catalog, because 

there are no delimiting parameters specified. 


Print a Key-Sequenced Cluster*s Data Records in a Catalog: Example 3 

In this example, the data records of a key-sequenced cluster, 

D40.EXAMPLE.KSDS1, are printed in dump format. That is, each 
character of the record is printed in its hexadecimal and 
alphameric forms. 

//PRINT1 JOB ... 

//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=A 
//SYSIN DD X 
PRINT - 

INDATASET(D40.EXAMPLE.KSDS1) 

/X 

The PRINT command prints data records of the key-sequenced 
cluster, D40.EXAMPLE.KSDS1. Its parameter is: 

• INDATASET, which names the data set to be printed. Because 
the data set is cataloged in D27UCAT1 and the high-level 
qualifier of the data set is the name of the alias of 
D27UCAT1, access method services can dynamically allocate 
the cluster without the need of JOBCAT or STEPCAT DD 
statements. 

Because neither FROMADDRESS, FROMKEY, SKIP, TOKEY, TOADDRESS, or 
COUNT is specified, access method services assumes that all the 
cluster’s data records are to be printed. 

Because neither HEX nor CHAR was specified, access method 
services prints each record in the DUMP format. An example of 
the printed record is shown in Figure 7 on page 224. 
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KCT OP RECQRO - OOFOFOFOFOFIC9C240C4C1405CC6C9 /f 

OMI OOFOFOF 0 F0FIC9E2 40C4CI40 SCC6C903 C540C9F0 C6F6F05C 40F5F040 D9C5C306 «.0000113 DA «FZLE 10080* 50 R€CO» 

i#ii 09C4E240 D6C640F6 F940C3CO C109E240 E6C9E3C8 4002C5E8 40C9D540 D7D6E240 *RDS OF 69 CHARS WITH KEY IN POS « 

0040 F160F1F1 48000000 00000000 00000000 *1-11. 


Figure 7. An Example of the Printed Record in DUMP Format (Result of Print Command) 


Copy Records from a Non-VSAM Data Set into an Entry-Sequenced VSAM Cluster# Then 
Print the Records: Example 4 

In this example, the first 15 records from a non-VSAM data set, 
EXAMPLE.N0NVSAM, are copied into an entry-sequenced cluster, 

D50.EXAMPLE.ESDS1. If the records were copied correctly, the 
cluster's records are printed in hexadecimal format. Finally, 
even if the records were not copied correctly, the non-VSAM data 
set's first 15 records are printed in character format. 

//PRINT2 JOB ... 

//JGBCAT DD DSNAME=USERCAT4,DISP=SHR 
// DD DSNAME=D27UCAT2,DISP=SHR 

//STEP1 EXEC PGM=IDCAMS 

//VSDSET2 DD DSNAME=D50.EXAMPLE.ESDS1,DISP=0LD 

//SYSPRINT DD 5YS0UT=A 
//SYSIN DD X 
REPR0 - 

INDATASET(EXAMPLE.N0NVSAM) - 
0UTFILECVSDSET2) - 
COUNT(15) 

IF LASTCC = 0 - 
THEN - 
PRINT - 

INFILE(VSDSET2) - 
HEX 


PRINT - 

INDATASET(EXAMPLE.N0NVSAM) - 

COUNT(15) - 

CHARACTER 


Job control language statements: 

• J0BCAT DD, which makes two catalogs available for this job: 
USERCAT4 and D27UCAT2. Concatenated J0BCAT DD statements 
were used to identify both catalogs. 

• VSDSET2 DD, which identifies the entry-sequenced VSAM 
cluster, D50.EXAMPLE.ESDS1, that the records are copied 
into. 

Note: If the AMP=(BUFND = n) parameter was specified, 

performance would improve when the data set's records are 
accessed. BUFND was allowed to default in this example, 
because only 15 records are being processed. 

The REPR0 command copies the first 15 records from the source 
data set, EXAMPLE.N0NVSAM, into the target entry-sequenced 
cluster, D50.EXAMPLE.ESDS1. Its parameters are: 

• INDATASET, which identifies the source data set, 

EXAMPLE.N0NVSAM. Because a J0BCAT DD statement is included 
with the job, VSAM will search for the catalog entry 
describing the non-VSAM data set in either USERCAT4 or 
D27UCAT2 user catalog, or in the master catalog. 
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• OUTFILE, which points to the VSDSET2 DD statement. The 
VSDSET2 DD statement identifies the output data set, 

D50.EXAMPLE.ESDS1. VSAM assumes that D50.EXAMPLE.ESDS1 is 
cataloged either in USERCAT4 or D27UCAT2 user catalog, or in 
the master catalog. 

• COUNT, which specifies that 15 records are to be copied. 
Because the SKIP parameter was not specified, access method 
services assumes that the first 15 records are to be copied. 
The records are always added after the last record in the 
output data set. 

The IF ... THEN command sequence verifies that the REPRO command 
completed successfully before the first PRINT command executes. 

The first PRINT command prints the records in the 
entry-sequenced cluster, D50.EXAMPLE.ESDS1. Its parameters ares 

• INFILE, which points to the VSDSET2 DD statement. The 
VSDSET2 DD statement identifies the cluster, 

D50.EXAMPLE.ESDS1. VSAM assumes that the cluster is 
cataloged either in the USERCAT4 or the D27UCAT2 user 
catalog, or in the master catalog. 

• HEX, which specifies that each record is to be printed as a 
group of hexadecimal characters. An example of the printed 
record is shown in Figure 8. 


RBA OF RECORD - 0 

C2D6E6C50940404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040 
4040404040404040404040404040404040404040 


Figure 8. An Example of the Printed Record in Hexadecimal (Result of PRINT Command) 


Note: The IF ... THEN command sequence ends with the HEX 

parameter, because no continuation character follows this 
parameter. If you want two or more access method services 
commands to execute only when the IF statement is satisfied, 
enclose the commands in a DO...END command sequence. 

The second PRINT command, which executes even if the REPRO 
command failed, prints the first 15 records of the non-VSAM data 
set, EXAMPLE.N0NVSAM. Its parameters are: 

• INDATASET, which identifies the non-VSAM data set 
EXAMPLE.N0NVSAM. VSAM will search for the catalog entry in 
either USERCAT4 or D27UCAT2 user catalog or in the master 
catalog. 

• COUNT, which specifies that 15 records are to be printed. 
Because SKIP was not specified, access method services 
assumes that the first 15 records are to be printed. 

• CHARACTER, which specifies that each record is to be printed 
as a group of alphameric characters. An example of the 
printed record is shown in Figure 9. 


RECORD SEQUENCE NUMBER - 3 
CLARK 

Figure 9. An Example of a Printed Alphameric Character Record (Result of PRINT 
Command) 
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REPRO 

REPRP 


The REPRO command copies VSAM and non-VSAM data sets, copies 
catalogs, and unloads and reloads VSAM catalogs. The format of 
this command is: 



{INFILE ( dd n aas E ''BassM&Ed 1 
E ENVIRONMENT(DUMMY)1)1 

INDATASETC entrvname t/ password ! 

E ENVIRONMENT(DUMMY)3)} 

{QUTFILE( ddname E/ password !)| 

OUTDATASET (e.p tcynamfiE/pa ssword ! U 

ESYSTEMKEYNAME( kev name )!)! 

E FROMKEY(key)IFROMADDRESS( a ddress )I 
FROMNUMBER( number )1SKIP( count )1 
EREPLACE I N0REPLACE 1 
EREUSE I NOREUSE 1 

ETOKEY(kev)ITOADDRESS( address )I 
TONUMBER( number )|COUNT( count )1 

[ENCIPHER 

({EXTERNALKEYNAME( kev name )I 
INTERNALKEYNAME( kev name )|PRIVATEKEYJ 
ECIPHERUNIT(ou mhsr ll)! 

E DATAKEYFILE( ddname )|DATAKEYVALUEE value )3 
ESHIPKEYNAMES( kev name ! kev name ...1)1 
E STOREDATAKEY| NOSTOREDATAKEY 1 
ESTOREKEYNAME( kev name )! 

EUSERDATA( value )!)1 
EDECIPHER 

({DATAKEYFILE( ddname )1 
DATAKEYVALUE( value )ISYSTEMKEV1 
E SYSTEMDATAKEY( value )3 


Note: The parameters ENCIPHER and DECIPHER apply only with the 
IBM Programmed Cryptographic Facility (5740-XY5) or the IBM 
Cryptographic Unit Support (5740-XY6). (For more information, 
see VSAM Administration Guide .) 


REPRO PARAMETERS 


Required Parameters 


INFILEE ddname E/ password lE ENVIRONMENT(DUMMY)3)| 

INDATASETE entrvname E/ password ! E ENVIRONMENT(DUMMY)1 ) 

identifies the source data set to be copied. If the 
logical record length of a non-VSAM source data set is 
greater than 32760 bytes, your REPRO command will terminate 
with an error message. 

INFILE( ddname E/ password l) 

specifies the name of the DD statement that identifies 
the data set to be copied. 

You can copy a base cluster in alternate-key sequence 
by specifying a path name as the data set name in the 
DD statement. 

Abbreviation: IFILE 

INDAT aset ( e n t n o m ni fi E /p assw or d 3 ! 

specifies the name of the entry to be copied. If 
INDATASET is specified, the entryname is dynamically 
allocated. 

You can copy a base cluster in alternate-key sequence 
by specifying a path name for entryname. 

Abbreviation: IDS 
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password 

is the read- or higher-level password of the data 
to be copied. If the data set is 
password-protected/ the read password must be 
supplied. If a catalog is to be copied, the 
master password is required. Passwords are 
applicable only to VSAM data sets. 

ENVIRONMENT (DUMMY) 

specifies that dummy ISAM records are to be copied. 
Dummy records are records with hexadecimal l FF l in the 
first byte. 

If you do not code the ENVIRONMENT parameter, dummy 
records will be ignored during the copy operation and 
will not be copied. (See 
for further information.) 

Abbreviations: ENV and DUM 

OUTFILE ( ridnauia E /fi ass mcd 3) I OUTDATASET! entryname [ / password 3 ) 

identifies the target data set. ISAM data sets cannot be 
specified as target data sets. If a VSAM data set defined 
with a record length greater than 32760 bytes is to be 
copied to a sequential data set, your REPRO command will 
terminate with an error message. 

OUTFILE( ddnamfi i /gassnocd 3 ) 

specifies the name of a DD statement that identifies 
the target data set. 

For VSAM data sets, the data set name can be that of a 
path. 

If the DD statement identifies a SYSOUT data set, the 
attributes must match those specified in "For a Target 
Data Set" on page 10. 

Abbreviation: 0 FIL E 

outdataset (.entr y na me C /gag s n& nd 3) 

specifies the name of the target data set. If 
OUTDATASET is specified, the entryname is dynamically 
allocated. 

For VSAM data sets, entryname can be that of a path. 
PjLg. SHQ JC. d 

specifies the update- or highei—level password 
for a password-protected target data set or path. 

Abbreviation: ODS 


Optional Parameters 

FRQMKEY(kev)|FROMADDRESS( address )| 

FRQMNUMBERC number )fSKIP! number ) 

specifies the location in the source data set from which 
copying is to start. If no value is coded, the copying 
begins with the first logical record in the data set. You 
can use only one of the four choices. 

The only parameter that can be used for a SAM data set is 
SKIP. 

If you are copying a catalog, none of these parameters can 
be specified; the entire catalog must be copied. 

The starting delimiter must be consistent with the ending 
delimiter. For example, if FROMADDRESS is specified for 
the starting location, use TOADDRESS to specify the ending 
location. The same is true for FROMKEY and TGKEY, and 
FRQMNUMBER and TONUMBER. 
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FROMKEYCkev) 

specifies the key of the first record you want copied. 

You can specify generic keys (that is, a portion of 

the key followed by X) . If you specify generic keys, U 

copying begins at the first record whose key matches 

that portion of the key you specified. 

You cannot specify a key longer than that defined for 
the data set. If you do, the data set is not copied. 

If the specified key is not found, the next higher key 
is used as the starting point for copying. 

FROMKEY may be specified only when an alternate index, 
a key-sequenced VSAM data set, or an 
indexed-sequential (ISAM) non-VSAM data set is being 
copied. 

kev 

can contain 1 to 255 EBCDIC characters. 

Abbreviation: FKEY 
FROMADDRESS(address) 

specifies the relative byte address (RBA) of the first 
record you want copied. The RBA value must be the 
beginning of a logical record. If you specify this 
parameter for key-sequenced data, the records will be 
copied in physical sequential order instead of in 
logical sequential order. 

FROMADDRESS: 

• Can be coded only for key-sequenced or 
entry-sequenced data sets or components. 

• Cannot be specified when the data set is being 

accessed through a path. \ 

• Cannot be specified for a key-sequenced data set 
with spanned records if any of those spanned 
records are to be accessed. 

Abbreviation: FADDR 

FRQMNUMBERt number ) 

specifies the relative record number of the first 
record you want copied. FROMNUMBER can be specified 
only when you copy a relative record data set. 

Abbreviation: FNUM 

SKiPtm unba c) 

specifies the number of logical records you want to 
skip before beginning to copy records. For example, 
if you want to copy beginning with record number 500, 
you specify SKIP(499). 

SKIP should not be specified when you access the data 
set through a path; the results are unpredictable. 

aridn ass f rmm.b e r . 

can be expressed in decimal (n), hexadecimal (X^ 1 ), 
or binary (B 1 ^) form; the expression cannot be longer 
than one fullword (8 decimal or hexadecimal numbers, 
or 32 binary numbers). 

REPLACE | NfiRE£JLME 

specifies whether a record in the source cluster (INFILE or 

INDATASET) is to replace a record in the target cluster 

(OUTFILE or OUTDATASET) when the source cluster is copied 

into the target cluster. /f’*\ 
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Because the catalog reload function automatically performs 
a REPLACE function, REPLACElNOREPLACE is ignored if the 
target data set is a VSAM catalog* 

When the source cluster is copied, its records might have 
keys or relative record numbers identical to the keys or 
relative record numbers of data records in the target 
cluster. When this is the case, the source record replaces 
the target record. 

REPLACE 

When a key-sequenced data set, other than a catalog, 
is copied, each source record whose key matches a 
target record’s key replaces the target record. 
Otherwise, the source record is inserted into its 
appropriate place in the target cluster. 

When a relative record data set is copied, each source 
record whose relative record number identifies a data 
record (rather than an empty slot) in the target data 
set replaces the target data record. Otherwise, the 
source data record is inserted into the empty slot its 
relative record number identifies. 

REPLACE cannot be used if the target data set is 
identified as a path through an alternate index, or if 
the target data set is a base cluster whose upgrade 
data set includes an alternate index defined with the 
unique key attribute. 

Abbreviation: REP 

NOREPLACE 

When a key-sequenced data set, other than a catalog, 
is copied, target records are not replaced by source 
records. For each source record whose key matches a 
target record's key, a ’’duplicate record” message is 
issued. 

When a relative record data set is copied, target 
records are not replaced by source records. For each 
source record whose relative record number identifies 
a target data record instead of an empty slot, a 
’’duplicate record” message is issued. 

Abbreviation: NREP 

REUSE I NOREUSE 

specifies whether the target data set is to be opened as a 
reusable data set. This parameter is valid only for VSAM 
data sets. 

REUSE 

specifies that the target data set, specified with 
OUTFILE or OUTDATASET, is opened as a reusable data 
set regardless of whether or not it was defined as 
reusable with the REUSE parameter. (See the DEFINE 
CLUSTER command description.) If the data set was 
defined with REUSE, its high-used relative byte 
address (RBA) is reset to zero (that is, the data set 
is effectively empty) and the operation proceeds. 

If REUSE is specified and the data set was originally 
defined with the NOREUSE option, the data set must be 
empty; otherwise, the REPRO command terminates with an 
error message. 

Abbreviation: RUS 
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specifies that records are to be written at the end of 
an entry-sequenced data set when QUTFILE or OUTDATASET 
identifies a nonempty data set. 

Abbreviation: NRUS 

TOKEYtk^y) iTOADDRESS(addr^) 1 

TONUMBER! number )|COUNT! number 3 

specifies the location in the data set being copied at 
which copying is to end. The location at which the copying 
is to end must follow the location at which it is to begin. 
If no value is coded/ the copying ends with the logical end 
of the data set or component. You can use only one of the 
four choices. 

The only parameter that can be specified for a SAM data set 
is COUNT. 

If you are copying a catalog, none of these parameters can 
be specified; the entire catalog must be copied. 

The ending delimiter must be consistent with the starting 
delimiter. For example, if FROMADDRESS is specified for 
the starting location, use TOADDRESS to specify the ending 
location. The same is true for FRGMKEY and TOKEY, and 
FROMNUMBER and TONUMBER. 

TOKEY!kev3 

specifies the key of the last record you want copied. 
You can specify generic keys (that is, a portion of 
the key followed by X) . If you specify generic keys, 
copying stops after the first record encountered that 
matches your key specifications. 

You cannot specify a key longer than that defined for 
the data set. If you do, the data set is not copied. 
If the specified key is not found, the next lower key 
is used as the end point for copying. 

TOKEY can be specified only when an alternate index, a 
key-sequenced data set, or an indexed-sequential 
(ISAM) non-VSAM data set is being copied. 

kev 

can contain 1 to 255 EBCDIC characters. 

TOADDRESS( address 3 

specifies the relative byte address (RBA) of the last 
record you want copied. Unlike FROMADDRESS, the RBA 
value does not need to be the beginning of a logical 
record. The entire record containing the specified 
RBA is copied. 

If you specify this parameter for a key-sequenced data 
set, the records will be copied in physical sequential 
order instead of in logical sequential order. 

TOADDRESS can be used only with VSAM key-sequenced or 
entry-sequenced data sets or components. TOADDRESS 
cannot be specified when the data set is accessed 
through a path. TOADDRESS cannot be specified for a 
key-sequenced data set with spanned records if any of 
those spanned records are to be accessed. 

Abbreviation: TADDR 

TONUMBERCn.y m b Qx J 

specifies the relative record number of the last 
record you want copied. TONUMBER can be specified 
only when you copy a relative record data set. 

Abbreviation: TNUM 
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count( num to .c) 

specifies the number of logical records you want 
copied. COUNT should not be specified when you access 
the data set through a path; the results are 
unpredictable. 

mm to e 

address^ number* and count can be expressed in decimal 
(n)* hexadecimal (X f n f )* or binary (B*n 9 ) form; the 
expression cannot be longer than one fullword (8 
decimal or hexadecimal numbers* or 32 binary numbers). 


CRYPTOGRAPHIC PARAMETERS 

ENCIPHER 

specifies that the target data set is to contain an 
enciphered copy of the source data set. 

The ENCIPHER parameter indicates that the source data set 
is to be enciphered as it is copied to the target data set. 

Abbreviation: ENCPHR 

EXTERNALKEYNAMEt kev name ] I 
INTERNAL-KEYNAME( kev name ) | PRIVATEKEY 

specifies whether keys are managed privately by you* 
or managed by the IBM Programmed Cryptographic 
Facility (5740-XY5) or the IBM Cryptographic Unit 
Support (5740-XY6). 

EXTERNALKEYNAMEC kev name ) 

specifies that keys are to be managed by the IBM 
Programmed Cryptographic Facility or the IBM 
Cryptographic Unit Support (574Q-XY6) and 
supplies the 1- to 8-character key name of the 
external file key to be used to encipher the data 
encrypting key. The key is only known by the 
system deciphering it. The key name and its 
corresponding enciphered data encrypting key will 
only be listed in SYSPRINT if NOSTOREDATAKEY is 
specified. 

Abbreviation: EKN 

INTERNALKEYNAMEC kev name ) 

specifies that keys are to be managed by the IBM 
Programmed Cryptographic Facility or the IBM 
Cryptographic Unit Support* and supplies the 1- 
to 8-character key name of the internal file key 
to be used to encipher the data encrypting key. 
The key is retained by the system creating the 
key. The key name and its corresponding 
enciphered data encrypting key will only be 
listed in SYSPRINT if NOSTOREDATAKEY is 
specified. 

Abbreviation: IKN 

PRIVATEKEY 

specifies that the key is to be managed by you. 
Abb reviation: P RIK EY 
ciPHERUNlTC nu m to c ID 

specifies that multiple logical source records are to 
be enciphered as a unit, number specifies the number 
of records that are to be enciphered together. By 
specifying that multiple records are to be enciphered 
together* you can improve your security (chaining is 
performed across logical record boundaries) and also 
improve your performance. However* there is a 
corresponding increase in main storage requirements. 
The remaining records in the data set* after the last 
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complete group of multiple records, will be enciphered 
as a group. (If number is 5 and there are 22 records 
in that data set, the last 2 records will be 
enciphered as a unit.) 

The value for number may range from 1 to 255. 
Abbreviation: CHPRUN 

DATAKEVFILE[ ddname )1DATAKEYVALUE( value ) 

specifies that you are supplying a plaintext (not 
enciphered) data encrypting key. If one of these 
parameters is not specified, REPRO will generate the 
data encrypting key. These parameters are only valid 
when EXTERNALKEYNAME or PRIVATEKEY is specified. If 
INTERNALKEYNAME and DATAKEYVALUE or DATAKEYFILE are 
specified, REPRO will generate the data encrypting key 
and DATAKEYVALUE or DATAKEYFILE will be ignored by 
REPRO. 

The plaintext data encrypting key will not be listed 
in SYSPRINT unless PRIVATEKEY is specified and REPRO 
provides the key. 

DATAKEYFILEt ddname ) 

identifies a a data set that contains the 
plaintext data encrypting key. For ddname, 
substitute the name of the JCL statement that 
identifies the data encrypting key data set. 

Abbreviation: DKFIL E 

DATAKEYVALUE( value ) 

specifies the 8-byte value to be used as the 
plaintext data encrypting key to encipher the 
data. 

value may contain 1 to 8 EBCDIC characters or 1 
to 16 hexidecimal characters coded (X f n f ). value 
must be enclosed in single quotation marks if it 
contains commas, semicolons, blanks, parentheses, 
or slashes. A single quotation mark must be 
coded as two single quotation marks. With either 
EBCDIC or hexadecimal representation, value is 
padded on the right with blanks (X^O 1 ) if it is 
fewer than 8 characters. 

Abbreviation: DKV 

SHIPKEYNAME( kev name C kev name ... 3) 

supplies the 1- to 8-character key name of one or more 
external file key(s) to be used to encipher the data 
encrypting key. Each key name and its corresponding 
enciphered data encrypting key will be listed in 
SYSPRINT, but will not be stored in the target data 
set header. The primary use for this parameter is to 
establish multiple enciphered data encrypting keys to 
be transmitted to other locations for use in 
deciphering the target enciphered data set. This 
parameter is only valid when INTERNALKEYNAME or 
EXTERNALKEYNAME is specified. 

Abbreviation: SHIPKN 

STOREDATAKEY i MSIMSMIMEI 

specifies whether the enciphered data encrypting key 
is to be stored in the target data set header. The 
key used to encipher the data encrypting key will be 
that identified by INTERNALKEYNAME or EXTERNALKEYNAME. 
This parameter is only valid when INTERNALKEYNAME or 
EXTERNALKEYNAME is specified. If the enciphered data 
encrypting key is stored in the data set header, it 
does not have to be supplied by the user when the data 
is deciphered. 
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Note: A data encrypting key enciphered under the keys 

identified by SHIPKEYNAME cannot be stored in the 
header. Therefore, you may want to avoid using 
STOREDATAKEY and SHIPKEYNAME together, because this 
could result in storing header information that is 
unusable at some of the locations involved. 

STOREDATAKEY 

specifies that the enciphered data encrypting key 
is to be stored in the target data set header. 

Abbreviation: STRDK 

NOSTOREDATAKEY 

specifies that the enciphered data encrypting key 
is not to be stored in the target data set 
header. The key name and its corresponding 
enciphered data encrypting key will be listed in 
SYSPRINT. 

Abbreviation: NSTRDK 
STQREKEYNAME( kev name ) 

specifies whether a key name for the key used to 
encipher the data encrypting key is to be stored in 
the target data set header. The key name specified 
must be the name by which the key is known on the 
system on which the REPRO DECIPHER is to be performed. 
This key name must be the same one that was specified 
in INTERNALKEYNAME if REPRO DECIPHER is to be run on 
the same system, but can be a different key name than 
that specified in INTERNALKEYNAME or EXTERNALKEYNAME 
if REPRO DECIPHER is to be run on a different system. 

This parameter is only valid when INTERNALKEYNAME or 
EXTERNALKEYNAME is specified. If the key name is 
stored in the data set header, it does not have to be 
supplied by the user when the data is deciphered. 

Note: key name values identified by the SHIPKEYNAME 

parameter cannot be stored in the header. Therefore, 
you may want to avoid using STOREKEYNAME and 
SHIPKEYNAME together, because this could result in 
storing header information that is unusable at some of 
the locations involved. 

Abbreviation: STRKN 

USERDATAC value ) 

specifies 1 to 32 characters of user data to be placed 
in the target data set header. This information could 
be used, for example, to identify the security 
classification of the data. 

value may contain 1 to 32 EBCDIC characters. If value 
contains a special character, enclose the value in 
single quotation marks (for example, 

USERDATAC 1 ^CONFIDENTIAL* 1 )). If the value contains a 
single quotation mark, code the embedded quotation 
mark as two single quotation marks (for example, 
USERDATAC 1 C0MPANY f, S 1 ) ) . 

You can code value in hexadecimal form, where two 
hexadecimal characters represent one EBCDIC character. 
For example, USERDATACX f C3D6D4D7ClD5E8 1 ) is the same 
as USERDATACCOMPANY). The string can contain up to 64 
hexadecimal characters when expressed in this form, 
resulting in up to 32 bytes of information. 

Abbreviation: UDATA 
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DECIPHER 

specifies that the target data set is to contain a 
plaintext (deciphered) copy of the enciphered source data 
set. 

The DECIPHER parameter indicates that the source data set 
is to be deciphered as it is copied to the target data set. 
The information from the source data set header is used to 
verify the plaintext data encrypting key supplied/ or 
deciphered from the information supplied/ as the correct 
plaintext data encrypting key for the decipher operation. 

Abbreviation: DECPHR 

DATAKEYFILEt ddname ) | DATAKEYVALUE( value ) | SYSTEMKEY 

specifies whether keys are to be managed privately by 
you/ or managed by the IBM Programmed Cryptographic 
Facility or the IBM Cryptographic Unit Support. 

DATAKEYFI LE( ddname ) 

specifies that the key is to be managed by you/ 
and identifies a data set that contains the 
private data encrypting key that was used to 
encipher the data. For ddname/ substitute the 
name of the JCL statement that identifies the 
data set containing the private data encrypting 
key. 

Abbreviation: DKFIL E 
DATAKEYVALUE ( value ) 

specifies that the key is to be managed by you/ 
and supplies the 1- to 8-byte value that was used 
as the plaintext private data encrypting key to 
encipher the data. For a discussion of how the 
method of supplying the data encrypting key 
relates to the security of the key/ see VSAM 
t ca,tjo g_G.M ide * 

value can contain 1 to 8 EBCDIC characters. 
value must be enclosed in single quotation marks 
if it contains commas/ semicolons/ blanks/ 
parentheses/ or slashes. A single quotation mark 
contained within value must be coded as two 
single quotation marks. You can code value in 
hexadecimal form/ (X f n*). value can contain 1 to 
16 hexadecimal characters/ resulting in 1 to 8 
bytes of information. With either EBCDIC or 
hexadecimal representation/ value is padded on 
the right with blanks (X^O 1 ) if it is fewer than 
8 characters. 

Abbreviation: DKV 

SYSTEMKEY 

specifies that keys are to be managed by the IBM 
Programmed Cryptographic Facility or the IBM 
Cryptographic Unit Support. 

Abbreviation: SYS K EY 

SYSTEMDATAKEY( value ) 

specifies the 1- to 8-byte value representing the 
enciphered system data encrypting key used to encipher 
the data. This parameter is only valid if SYSTEMKEY 
is specified. If SYSTEMDATAKEY is not specifed/ REPRO 
will obtain the enciphered system data encrypting key 
from the source data set header/ in which case/ 
STOREDATAKEY must have been specified when the data 
set was enciphered. 

value may contain 1 to 8 EBCDIC characters, value 
must be enclosed in single quotation marks if it 
contains commas/ semicolons/ blanks/ parentheses/ or 





/O. 
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slashes. A single quotation mark must be coded as two 
single quotation marks. You can code value in 
hexadecimal form/ (X f n f ). value can contain 1 to 16 
hexadecimal characters/ resulting in 1 to 8 bytes of 
information. With either EBCDIC or hexadecimal 
representation/ value is padded on the right with 
blanks (X^O 1 ) if it is fewer than 8 characters. 

Abbreviation: SYSDK 

SYSTEMKEYNAME( key name ! 

specifies the 1- to 8-character key name of the 
internal key that was used to encipher the data 
encrypting key. This parameter is only valid if 
SYSTEMKEY is specified. If SYSTEMKEYNAME is not 
specified/ REPRO will obtain the key name of the 
internal key from the source data set header/ in which 
case, STOREKEYNAME must have been specified when the 
data set was enciphered. 

Abbreviation: SYSKN 
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Copy Records into a Key Sequenced Data Set: Example 1 

In this example, records from an indexed-sequential data set, 

ISAMDSET, are copied into key-sequenced VSAM cluster, 

D40.EXAMPLE.KSDS1. 

//REPR01 JOB 

//STEP1 EXEC PGM=IDCAMS 

//INDSET1 DD DSNAME=ISAMDSET,DISP=0LD, 

// DCB=(DSQRG=IS,BUFN0=6) 

//SYSPRINT DD SYSQUT=A 

//SYSIN DD * 

REPRO - 

INFILECINDSET1) - 
QUTDATASETCD40.EXAMPLE.KSDS1) 

/x 

Job control language statement: 

• INDSET1 DD, which describes the indexed-sequential data set, 
ISAMDSET, that contains the source records. The BUFNO 
parameter specifies the number of buffers assigned to the 
ISAM data set. This improves performance when the ISAM data 
set"s records are accessed. 

The REPRO command copies all records from the source data set, 

ISAMDSET, to the target data set, D40.EXAMPLE.KSDS1. Its 

parameters are: 

• INFILE, which points to the INDSET1 DD statement. The 
INDSET1 DD statement identifies the source data set: 
ISAMDSET. ISAMDSET is an indexed-sequential data set. 

• OUTDATASET, which identifies the key-sequenced VSAM cluster 
into which the source records are to be copied. This data 
set is dynamically allocated by access method services. 
Catalog D27UCAT1 will be searched for the data set, because 
D40 is an alias for D27UCAT1. 
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Copy Records into a VSAM Data Set: Example 2 

In this two-part example, data records are copied from the 
non-VSAM data set SEQ.D27V, a sequential data set, into a 
key-sequenced VSAM data set, D40.MYDATA. Next, records are 
copied from the key-sequenced data set, D40.MYDATA, into an 
entry-sequenced data set, ENTRY. 

//REPR02 JOB ... 

//JOBCAT DD DSNAME=USERCAT3,DISP=SHR 

//STEP1 EXEC PGM=IDCAMS 

//INPUT DD DSNAME=SEQ.D27V,DISP=SHR,DCB=(BUFN0=6) 

//SYSPRINT DD SYS0UT=A 

//SYSIN DD X 

REPRO - 

INFILECINPUT) - 
OUTDATASET C D40.MYDATA) 

/x 

//STEP2 EXEC PGM=IDCAMS 

//INPUT DD DSNAME=D40.MYDATA,DISP=0LD 

//OUTPUT DD DSNAME=ENTRY,DISP=0LD 

//SYSPRINT DD SYS0UT=A 

//SYSIN DD X 

REPRO - 

INFILECINPUT) - 
OUTFILECOUTPUT) - 
FROMKEY(DEAN) - 
TOKEYCJOHNSON) 

/x 

STEP1: Access method services copies records from a sequential 

data set, SEQ.D27V, into a key-sequenced data set, D40.MYDATA. 
STEPl's job control language statements: 

• JOBCAT DD, which makes the catalog USERCAT3 available for 
this job. 

• INPUT DD, which identifies the sequential data set, 

SEQ.D27V, that contains the source records. The BUFNO 
parameter specifies the number of buffers assigned to the 
sequential data set. This improves performance when the 
data set’s records are accessed. 

STEPl’s REPRO command copies all records from the source data 
set, SEQ.D27V, to the target data set, D40.MYDATA. Its 
parameters are: 

• INFILE, which points to the INPUT DD statement. The INPUT 
DD statement identifies the source data set. 

• OUTDATASET, which identifies the key-sequenced data set into 
which the source records are to be copied. The data set is 
dynamically allocated by access method services. 

STEP2: Access method services copies some of the records of the 

key-sequenced data set D40.MYDATA into another entry-sequenced 
data set, ENTRY. STEP2’s job control language statements: 

• JOBCAT DD, which applies to this job step as well as to 
STEP1. 

• INPUT DD, which identifies the key-sequenced cluster, 

D40.MYDATA, that contains the source records. 

• OUTPUT DD, which identifies the entry-sequenced cluster, 
ENTRY, that the records are to be copied into. 

STEP2 f s REPRO command copies records from the source data set, 
D40.MYDATA, to the target data set, ENTRY. Only those records 
with key values from DEAN to, and including, JOHNSON are copied. 
The REPRO command’s parameters are: 

• INFILE, which points to the INPUT DD statement. The INPUT 
DD statement identifies the source key-sequenced data set. 
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• OUTFILE, which points to the OUTPUT DD statement. The 
OUTPUT DD statement identifies the entry-sequenced data set 
into which the source records are to be copied. 

• FROMKEY and TOKEY, which specify the lower and upper key 
boundaries. Only those records with key values from DEAN 
to, and including^ JOHNSON are copied. 

If ENTRY already contains records/ VSAM merges the copied 
records with ENTRY'S records. A subsequent job step could 
resume copying the records into ENTRY/ beginning with the 
records with key greater than JOHNSON. If you subsequently 
copied records with key values less than DEAN into ENTRY/ VSAM 
merges them with ENTRY'S records. 
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Copy a Catalog: Example 3 


In this example, a catalog is copied to illustrate the catalog 
copying procedure. 


//COPYCAT JOB 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYS0UT=A 

//SYSIN DD x 

DEFINE USERCATALOG - 
C NAME(CQPYUCAT) - 

MASTERPWCUCATMPW) - 
UDATEPWC UCATUPW) - 
FORC365) “ 
VOLUMECVSER06) ) - 
CYLINDERSC100 10) ) - 


/X 

DATA - 

(CYLINDERSC20 10) ) - 
INDEX - 

(CYLINDERSC10) ) - 
CATALOG - 

(AMASTCAT/MRCATPW2) 

//STEP2 

EXEC 

PGM=IDCAMS 

//STEPCAT 

DD 

DSNAME=CQPYUCAT,DISP=i 

// 

DD 

DSNAME=MYCAT,DISP=0LD 

//SYSPRINT 

DD 

SYSOUT=A 

//SYSIN 

REPRO 

DD 

X 


INDATASET(MYCAT) - 
OUTDATASET C COPYUCAT/UCATMPW) 
EXPORT - 

MYCAT - 
DISCONNECT 
/X 

//STEP3 EXEC PGM=IDCAMS 

//STEPCAT DD DSNAME=COPYUCAT,DISP-SHR 

//SYSPRINT DD SYSOUT=A 

//SYSIN DD X 

LISTCAT 


/x 

//STEP4 EXEC PGM=IDCAMS 

//STEPCAT DD DSNAME=CQPYUCAT,DISP=OLD 

//SYSPRINT DD SYSOUT=A 

//SYSIN DD x 

DELETE - 

MYCAT - 
CLUSTER - 
PURGE - 

CATALOG(COPYUCAT/UCATMPW) 


/X 

//STEPS EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD X 
DEFINE ALIAS - 

(NAME(MYCAT) - 
RELATE(COPYUCAT) ) 
/x 


STEP1: A user catalog, COPYUCAT, is defined on volume VSER06. 

The catalog entries in MYCAT will be copied into COPYUCAT. 


The DEFINE USERCATALOG command defines the user catalog, 
COPYUCAT. Its parameters are? 

• NAME, which specifies the name of the new catalog, COPYUCAT. 

• MASTERPW and UPDATEPW, which specify the master and update 
level passwords for the catalog. 

• FOR, which specifies that the catalog is to be retained for 
365 days. 


Chapter 4. Functional Command Format 239 







REPRO 


• VOLUME# which specifies that the catalog is to reside on 
volume VSER06. 

• CYLINDERS, which specifies that the catalog's data space is 
initially to be 100 cylinders. When the data space is 
extended/ it is to be extended in increments of 10 
cylinders. Part of the data space contains the catalog/ 
COPYUCAT. The rest of the data space is available for 
suballocated VSAM data sets. 

• DATACCYLINDERS) and INDEXCCYLINDERS) specify that the 
catalog itself is initially to occupy 30 cylinders. When 
the catalog's data component is extended/ it is to be 
extended in increments of 10 cylinders. 

• CATALOG/ which specifies that a user catalog connector entry 
is to be built and written into the AMASTCAT catalog. The 
user catalog connector entry points to COPYUCAT. 

STEP2: Access method services copies the contents of MYCAT into 

COPYUCAT. 

STEP2's job control statement: 

• STEPCAT DD/ which makes two catalogs available for this job 

step: COPYUCAT and MYCAT. The DD statements that identify 

the catalogs are concatenated. 

The REPRO command copies all records from MYCAT into COPYUCAT. 
Access method services treats each catalog as a key-sequenced 
data set and copies each catalog record. Consequently/ the 
first 13 catalog records of MYCAT/ which describe MYCAT as a 
key-sequenced data set/ are also copied into COPYUCAT. Entries 
from MYCAT are written into COPYUCAT beginning with catalog 
record 14 (that is, after the 13 self-describing records of 
COPYUCAT). The REPRO command's parameters are: 

• INDATASET/ which identifies the source data set: MYCAT. 

VSAM assumes that MYCAT is cataloged in either MYCAT or 
COPYUCAT. 

• 0UTDATASET/ which identifies the receiving data set: 
COPYUCAT. VSAM assumes that COPYUCAT is cataloged in either 
COPYUCAT or MYCAT. 

The EXPORT command removes MYCAT f s user catalog connector entry 
from the master catalog. MYCAT's cataloged objects are now not 
available to the system. (STEPS builds an alias entry that 
relates MYCAT to COPYUCAT/ making the cataloged objects 
available to the system again.) 

STEP3: Access method services lists the name of each entry in 

the new catalog/ COPYUCAT. The STEPCAT DD statement identifies 
the catalog to be listed. 

LISTCAT cannot run in a job step where the catalog is empty when 
it is opened. To ensure that the LISTCAT correctly reflects the 
contents of the catalog/ the LISTCAT was run as a separate job 
step. 

STEP4: Access method services removes the entries in COPYUCAT 

that describe MYCAT as a key-sequenced data set. (See STEP2 
description above.) The DELETE command's parameters are: 

• MYCAT/ which identifies the object to be deleted. 

• CLUSTER/ which specifies that MYCAT is cataloged as a 
cluster in COPYUCAT. MYCAT's cluster/ data, and index entry 
are removed from COPYUCAT. 

• PURGE/ which specifies that MYCAT is to be deleted 
regardless of a specified retention period or date. 
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• CATALOG, which specifies that MYCAT is cataloged in 

COPYUCAT. COPYUCAT's master password, UCATMPW, is required 
to delete its catalog entries. 

STEPS: Access method services builds an alias entry that 

relates MYCAT to COPYUCAT. Because no CATALOG parameter or 
JOBCAT or STEPCAT DD statement identifies the catalog that is to 
contain the alias entry, VSAM assumes the entry is to be written 
into the master catalog. 

When MYCAT was defined, it was defined on volume VSER04. Its 
catalog entries describe VSAM objects on that volume. COPYUCAT 
is defined on volume VSER06. Because MYCAT was copied into 
COPYUCAT (and MYCAT no longer exists as a user catalog), 

COPYUCAT entries now describe VSAM objects on volumes VSER04 and 
VSER06. 


Unload a VSAM User Catalog: Example 4 


This example shows how a VSAM user catalog can be unloaded to 
tape using the catalog unload/reload feature of the REPRO 
command. 


//UNLOAD JOB 
//JOBCAT DD 
//STEP1 EXEC 

//SYSPRINT DD 
//CATIN DD 

//CATOUT DD 
// 

// 


//SYSIN DD 
REPRO - 


DSNAME=D27UCAT2,DISP=QLD 
PGM=IDCAMS 
SYSOUT=A 

DSNAME=D27UCAT2,DISP=0LD 
DSNAME=PORTABLE.TAPE,LABEL=(1,SL), 
DISP = NEW,UNIT=TAPE,VQL = SER=TAPE01, 
DCB=(DEN=3,RECFM=VB,LRECL=516,BLKSIZE=5164) 


INFILECCATIN/USERMRPW) - 
OUTFILECCATOUT) 


/x 


Job control language statements: 

• JOBCAT DD, which is required, and which identifies and 
allocates the user catalog as the job catalog. 

• CATIN DD, which describes and allocates the user catalog, 
D27UCAT2, as a VSAM data set to be opened and used by the 
REPRO command as the source data set for the unload 
operation. 

• CATOUT DD, which describes and allocates a magnetic tape 
file to contain the copy of the catalog. The DCB parameters 
must be specified as shown. The BLKSIZE parameter can be 
any multiple of LRECL plus 4, where LRECL=516. 

The REPRO command causes the VSAM user catalog D27UCAT2 to be 

unloaded (that is, copied) to a magnetic tape file. The REPRO 

command's parameters are: 

• INFILE, which is required, and which identifies the user 
catalog as a source VSAM data set. The catalog's master 
password is required to open it as a data set. 

• OUTFILE, which is required, and which describes the magnetic 
tape file, or target data set that is to contain the 
catalog's copy. 
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Reload an Unloaded VSAN User Catalog: Example 5 

This example shows how a VSAM user catalog can be reloaded from 
the backup copy, created in the previous example/ using the 
catalog unload/reload feature of the REPRO command. 

//RELOAD JOB ... 

//JOBCAT DD DSNAME=D27UCAT2,DI$P=QLD 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYS0UT=A 

//CATIN DD DSNAME=PQRTABLE.TAPE/LABEL=(1,SL)/ 

// DISP=OLD/UNIT=TAPE/VOL=SER=TAPE01/DCB=DEN=3 
//CATOUT DD DSNAME=D27UCAT2/DISP=0LD 

//SYSIN DD X 

REPRO - 

INFILE(CATIN) - 
OUTFILECCATOUT/USERMRPW) 

/x 

Job control language statements: 

• JOBCAT DD/ which is required and which describes and 
allocates the user catalog to be reloaded. The JOBCAT 
statement specifies that D27UCAT2 is the job catalog. 

• CATIN DD/ which describes and allocates the magnetic tape 
file that contains the unloaded copy of the catalog. 

Because a standard label tape is used/ DCB parameters of 
record format/ record size, and block size need not be 
specified. For a nonlabeled tape, the same parameters as in 
the previous example must be specified. 

• CATOUT DD/ which describes the user catalog as a VSAM d^ta 
set to be opened and used by REPRO as the target data set 
for the reload operation. 

The REPRO command causes a VSAM user catalog to be reloaded from 
the backup copy created in the previous example. The REPRO 
command's parameters are: 

• INFILE/ which is required/ and which identifies the magnetic 
tape file that contains the unloaded/ or backup/ copy of the 
user catalog. 

• QUTFILE/ which is required and which identifies the user 
catalog as a VSAM data set to be opened for record 
processing. The master password allows opening the catalog 
as a data set. 


Encipher Using System Keys: Example 6 

In this example/ an enciphered copy of part of a VSAM relative 
record data set is produced using a tape as output. The 
enciphered data set is to be deciphered at a remote 
installation. Four source records at a time will be enciphered 
as a unit. The keys will be managed by the IBM Programmed 
Cryptographic Facility or the IBM Cryptographic Unit Support. 
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( 


//ENSYS JOB 

//JOBCAT DD DSN-D27UCAT,DISP=SHR 
//STEP1 EXEC PGM=IDCAMS 
//CLEAR DD DSN=RRDS1,DISP=SHR 
//CRYPT DD DSN=RRDSEN,LABEL=C1,SL),DISP=NEW 
UNIT=TAPE,VOL=SER=TAPEQl, 

DCB=(DEN=3,RECFM=FB,LRECL=516,BLKSIZE=516Q) 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD X 
REPRO - 

INFILECCLEAR/RDPW) - 
OUTFILE(CRYPT) - 
COUNTC50) - 
ENCIPHER - 

(EXTERNALKEYNAMECAKEY27) - 
STOREDATAKEY - 
CIPHERUNITC4) - 
USERDATA(CONF)) 

/x 

Job control language statements! 

• JOBCAT DD makes the catalog D27UCAT available. 

• CLEAR DD describes the relative record data set. 

• CRYPT DD describes and allocates a magnetic tape file. 

LRECL is the relative record data set record size plus 4. 

The REPRO command copies 50 records enciphered from a generated 
data encrypting key, from the source data set, RRDS1, to the 
output tape. The source records will be enciphered in units of 
four records, except for the last two records, which will be 
enciphered together. The enciphered data encrypting key will be 
stored in the header of the target data set; therefore, REPRO 
will not list the key name or enciphered data encrypting key in 
SYSPRINT. The parameters of the REPRO command are: 

• INFILE points to the CLEAR DD statement, identifying the 
source data set to be enciphered, RRDS1. RRDS1 is cataloged 
in either D27UCAT or the master catalog. The read password 
for the source data set is RDPW. 

• OUTFILE points to the CRYPT DD statement, identifying the 
target data set on tape. 

• COUNT indicates the copy operation is to end after 50 
records have been copied. 

• ENCIPHER indicates that the target data set is to contain an 
enciphered copy of the source data set. 

• EXTERNALKEYNAME supplies the name, AKEY27, of the external 
file key to be used to encipher the data encrypting key. 

• STOREDATAKEY indicates that the data encrypting key 
enciphered under the secondary file key is to be stored in 
the header of the target data set. 

• CIPHERUNIT indicates that 4 source records at a time are to 
be enciphered as a unit. 

• USERDATA specifies a character string, l C0NF l , to be stored 
in the header of the target data set as user data. 
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In this example, the enciphered data set produced by the job in 
Example 6 is deciphered at the remote location, using a VSAM 
relative record data set as the target for the plaintext 
(deciphered) data. The empty slots in the original data set 
will be reestablished. Keys will be managed by the IBM 
Programmed Cryptographic Facility or the IBM Cryptographic 
Support Unit. 

//DESYS JOB 

//JOBCAT DD DSN=D27UCATR,DISP=SHR 
//STEP2 EXEC PGM=IDCAMS 

//CRYPT DD DSN=RRDSEN,LABEL=(1,SL),DISP=0LD, 

UNIT=TAPE,V0L = SER=TAPE01, 

DCB=DEN=3 

//CLEAR DD DSN=RRDS2,DISP=SHR 
//SYSPRINT DD SY$0UT=A 
//SYSIN DD x 
REPRO - 

INFILECCRYPT) - 
0UTFILECCLEAR/UPPW2) - 
DECIPHER - 
(SYSTEMKEY - 
SYSTEMKEYNAMEC BKEY27)) 

/x 

Job control language statements: 

• JOBCAT DD makes the catalog D27UCATR available. 

• CRYPT DD describes and allocates the magnetic tape 
containing the enciphered data. 

• CLEAR DD describes the relative record data set. 

The REPRO command copies and deciphers the enciphered data set 
from the source tape to the target data set RRDS2. The 
enciphered data encrypting key is obtained from the header of 
the source data set. The internal file key (BKEY27) is used to 
decipher the enciphered data encrypting key, which is then used 
to decipher the data. The parameters of the REPRO command are: 

• INFILE points to the CRYPT DD statement, identifying the 
tape containing the enciphered source data. 

• OUTFILE points to the CLEAR DD statement, identifying the 
data set to contain the deciphered data, RRDS2. RRDS2 is 
cataloged in either D27UCATR or the master catalog. The 
defined record size must be the same as that of the original 
relative record data set. The update password for the 
target data set is UPPW2. 

• DECIPHER indicates that the source data set is to be 
deciphered as it is copied to the target data set. 

• SYSTEMKEY indicates that keys are to be managed by the IBM 
Program Cryptographic Facility or the IBM Cryptographic Unit 
Support. 

• SYSTEMKEYNAME supplies the key name, BKEY27, of the internal 
file key that was used to encipher the system data 
encrypting key. The file key must be an internal file key 
in this system. 
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Encipher Using Private Keys: Example 8 

In this example, an enciphered copy of a SAM data set is 
produced by using an entry-sequenced data set as the target data 
set. The enciphered data set resides on a volume that is to be 
stored offline at the local installation. Each record in the 
target data set will be enciphered separately, using a data 
encrypting key supplied by the user via a data encrypting key 
data set. Keys will be managed privately by the user. 


//ENPRI JOB 

//JOBCAT DD DSN=D27UCAT,DISP=SHR 

//STEP1 EXEC PGM=IDCAMS 

//CLEAR DD DSN=SAMDS1,DISP=0LD, 

VOL=SER=VQL0O5,UNIT=DISK 
//CRYPT DD DSN = E5DS1,DISP=0LD 

//KEYIN DD x 

53467 568503A7C29 

/X 

//SYSPRINT DD SYS0UT=A 

//SYSIN DD X 

REPRO - 

INFILE(CLEAR) - 
OUTFILECCRYPT/UPPW) - 
REUSE - 
ENCIPHER - 
(PRIVATEKEY - 
DATAKEYFILECKEYIN)) 

/x 


Job control language statements: 

• JOBCAT DD makes the catalog D27UCAT available. 

• CLEAR DD describes the SAM data set. 

• CRYPT DD describes the entry-sequenced data set. 

• KEYIN DD describes the data encrypting key data set 

consisting of a single record containing the data encrypting 
key. 

The REPRO command copies all records enciphered under the 
supplied data encrypting key, from the source data set, SAMDS1, 
to the target data set, ESDS1. The plaintext private data 
encrypting keys will not be listed on SYSPRINT, because the user 
manages the key. The parameters of the REPRO command are: 

• INFILE points to the CLEAR DD statement, identifying the 
source data set to be enciphered, SAMDS1. 

• OUTFILE points to the CRYPT DD statement, identifying the 
target data set, ESDS1. ESDS1 is cataloged in either 
D27UCAT or the master catalog. The defined maximum record 
size of the entry-sequenced data set must be large enough to 
accommodate the largest SAM record. 

• REUSE indicates that the target data set is to be opened as 
a reusable data set. If the data set was defined as REUSE, 
it is reset to empty; otherwise, the REPRO command will 
terminate. 

• ENCIPHER indicates that the target data set is to contain an 
enciphered copy of the source data set. 

• PRIVATEKEY indicates that the key is to be managed by the 
user. 

• DATAKEYFILE points to the KEYIN DD statement, which supplies 
the plaintext data encrypting key, X*53467568503A7C29*, to 
be used to encipher the data. 
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In this example, the enciphered data set produced by the job in 
Example 8, is deciphered at the same location, using an 
entry-sequenced data set as the target for the plaintext 
(deciphered) data. Keys will be managed privately by the user. 


//DEPRI JOB 
//JOBCAT DD 
//STEP1 
//CRYPT DD 
//CLEAR DD 
//SYSPRINT DD 
//SYSIN DD 
REPRO - 


DSN=D27UCAT,DISP=SHR 
EXEC PGM=IDCAMS 

D$N=ESDS1,DISP=0LD 
DSN=ESDS3,DISP=0LD 
SYSOUT=A 
X 


INFILECCRYPT/RDPWl) - 
0UTFILECCLEAR/UPPW3) - 
DECIPHER - 

(DATAKEYVALUECX 1 53467568503A7C29 1 ) ) 


/X 


Job control language statements: 

• JOBCAT DD makes the catalog D27UCAT available. 

• CRYPT DD describes the enciphered source entry-sequenced 
data set. 

• CLEAR DD describes the target entry-sequenced data set. 

The REPRO command copies and deciphers the enciphered data set 

from the source data set, ESDS1, to the target data set, ESDS3. 

The supplied plaintext data encrypting key is used to decipher 

the data. The parameters of the REPRO command are: 

• INFILE points to the CRYPT DD statement, identifying the 
source data set to be enciphered, ESDS1. ESDS1 is cataloged 
in either D27UCAT or the master catalog. The read password 
for the source data set is RDPW1. 

• OUTFILE points to the CLEAR DD statement, identifying the 
target data set, ESDS3. ESDS3 is cataloged in either 
D27UCAT or the master catalog, and must be empty. The 
defined maximum record size of the target entry-sequenced 
data set must be large enough to accommodate the largest 
source entry-sequenced data set record. The update password 
for the target data set is UPPW3. 

• DECIPHER indicates that the source data set is to be 
deciphered as it is copied to the target data set. 

• DATAKEYVALUE indicates that keys are to be managed by the 
user, and supplies the plaintext private data encrypting 
key, X*53467568503A7C29 1 , which was used to encipher the 
data. 
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RE S ETC A T 

( 


The RESETCAT command compares catalog entries with catalog 
recovery area (CRA) entries in order to regain access to catalog 
data. This command is for use with recoverable catalogs only . 

The format of the RESETCAT command is: 


RESETCAT 


CATALOG(. c ajtQameC/j B&ggH &nd3 £ ddjmm&l 3 
CCRAFILESC( ddnamel C ALL 1 NONE!) 

[( ddnamel i ALL 1 NONE!)...Ill 
CRAVOLUMESC (voider E . d§yty , P .e3 3 
CCyglserC d e y t yjP.e.3 3.. J)} 

£ IGNOREi NOIGNORE 3 
EHASTERFVa password )3 
EWORKCATC catname C/ password ))3 
CWORKFILECddpanLeE/^assmcd3 )3 


RESETCAT may be abbreviated: RCAT. 


RESETCAT PARAMETERS 


Required Parameters 


CATALOG Ccg±Q<ams£ /password 3 £ddnamg3 ) 

identifies the catalog to be reset. The catalog specified 
by catname must have the RECOVERABLE attribute. 

Exclusive control of the catalog is required throughout the 
duration of the command. Also, no VSAM data sets cataloged 
in the catalog may be open. The master catalog may not be 
reset while it is in use as a master catalog. 

Eaas3fttpx. d 

specifies the catalog f s master password. If the 
catalog is password protected, you must specify the 
master password of the catalog. RACF: The alter RACF 
authority to the catalog is required. 

ddname 

specifies the name of the DD statement for the catalog 
being reset. If ddname is not specified, the catalog 
will be dynamically allocated, ddname must also be 
specified in a JOBCAT or STEPCAT. 

Abbreviation: CAT 

CRAFILESC( ddnamel E ALL f NONE3 )...) 

specifies a list of DD statements that identify the volumes 
and devices to be used to reset the catalog. Each volume 
contains a CRA that has a copy of the catalog records 
describing the VSAM objects on that volume. ALL specifies 
that the catalog records in the CRA on the volume specified 
by ddnamel are to be reset. 

If a volume contains a multivolume data set whose catalog 
entry is being reset, other volumes of that multivolume 
data set may be needed during the reset operation; you 
should specify these via additional ddnamel parameters. 

Use the NONE subparameter if you do not want the entries in 
these additional volumes to be used to reset the catalog. 

If a volume is needed and you do not specify the DD 
statements provided by CRAFILES, it will be allocated 
dynamically, and will assume the NONE attribute. 

CRAVOLUMESC (yj>j£gr E g.e,33...3 

specifies the volume serial numbers and corresponding 
device types of the volumes used in resetting the catalog. 
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Each volume contains a catalog recovery area (CRA) that has 
a copy of the catalog records that describe the objects on 
the volume. The volume is allocated dynamically. 

volser 

specifies the volume serial number used in resetting 
the catalog. 

specifies the device type for the associated volser. 

If you do not specify devtype, the volume must be 
mounted and on a unit marked permanently resident or 
reserved. If you specify a generic name for devtype, 
the volume need not be mounted. 

If a volume contains a multivolume data set whose 
catalog entry is being reset, other volumes of that 
multivolume data set may be needed during the reset 
operation; if needed and not specified for reset, 
these volumes will be allocated dynamically. 
Dynamically allocated volumes assume the NONE 
attribute as described for the CRAFILES parameter. 

Abbreviation: CRAVOL 


Optional Parameters 


IGNORE1 N0IGNQRE 

specifies whether RESETCAT should continue processing and 
force the reset when certain errors are encountered. These 
errors may be: 

• I/O error in the catalog. 

• I/O error in the CRA. 

• The volume record or its extensions in the CRA are in 
error. 

IGNORE 

specifies that the RESETCAT command will try to 
recover as much information as possible and reset the 
catalog's description of those data sets on the 
specified volumes. 

For example, if IGNORE is specified and an I/O error 
occurs while processing a record from a CRA, that 
record will be ignored. In the process, data sets 
that could not be recovered on a particular volume 
would be marked unusable on that volume, and the space 
that was assigned to them would be freed. 

Abbreviation: IGN 

NOIGNORE 

specifies that I/O errors result in immediate 
termination. 

Abbreviation: NIGN 

HASTERPW(msskifind) 

specifies the master catalog's master password when the 
master catalog is password protected. 

WORKCAT t £&±r&m t /p^SS H P.C d 3) 

specifies the name of the catalog in which RESETCAT defines 
the WORKFILE. This catalog must not be the same as the 
catalog being reset. The catalog must be specified in a 
JOBCAT or STEPCAT DD statement. 

If you do not specify the WORKCAT parameter, the catalog 
will be chosen using existing rules for "Order of Catalog 
Selection for DEFINE" on page 16. 
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If you do not specify the WORKCAT parameter, the catalog 
must be the first DD statement in the JQBCAT or STEPCAT DD 
statement concatenation. However, if the work file catalog 
is the master catalog, then you must specify the WORKCAT 
parameter and it must be the last DD statement in the 
JOBCAT or STEPCAT DD statement concatenation. The 
resultant catalog must not be the same as the one being 
reset. 

E& s s mn d 

If the catalog is password protected, the update- or 
highei—level password is required. RACFi The update 
or higher RACF authority to the catalog is required. 

Abbreviation: WCAT 

WQRKF ILE C ddnamsC/passaged3) 

specifies the name of a DD statement that identifies a VSAM 
data set name and a list of volume serial numbers of 
volumes containing VSAM data spaces and units to be used by 
RESETCAT for a work file. These volumes must be owned by 
the catalog in which the work file is defined. 

This data set will be defined by RESETCAT and used as 
temporary storage while processing the command; it will be 
deleted at the end of the command. The data set must not 
be already defined. 

Space requirements for the data set are noted in "WORKFILE 
Space Requirements” in C al aJ L . Q fl. J\ . If 
you do not specify WORKFILE, IDCUT1 is used as a default 
ddname. 

pjass Mocri 

If you require one, you may specify a password to be 
used by RESETCAT to password protect the work file. 
Because the work file will contain a copy of the 
catalog records, it may contain security-sensitive 
information. The password you specify will become the 
work file f s master password. You may specify the 
password only if ddname is explicitly specified. 

Abbreviation: WFILE 
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Resetting a Catalog: Example 1 

This example illustrates the use of RESETCAT to reset a catalog 
(USERCAT1), one of whose owned volumes (VSER01) has been 
restored. The other volume owned by USERCAT1 is VSER02. 


//RECOVER 

JOB 

• • • 

//STEP1 

EXEC 

PGM=IDCAMS 

//SYSPRINT 

DD 

SYS0UT=A 

//STEPCAT 

DD 

DSN=USERCAT1,DISP=0LD 

// 

DD 

DSN=AMASTCAT,DISP=0LD 

//IDCUT1 

DD 

DSN=WORKFILE,DISP=OLD, 

// 

VOL 

=SER=333333,UNIT=DISK> AMP='AMORG* 

//CRAV0L1 

DD 

DISP=OLD,VOL=SER=VSER01,UNIT=DISK 

//CRAV0L2 

DD 

DISP=OLD,VOL=SER=VSER02,UNIT=DISK 

//DDCAT 

DD 

DSN=USERCAT1,DISP=0LD 

//SYSIN 

DD 

X 


RESETCAT - 

CATAL0GCUSERCAT1/MASTER DDCAT) - 
CRAFILESCCCRAV0L1 ALL) CCRAV0L2 NONE)) - 
WORKCATCAMASTCAT/MCATMRPW) - 
MASTERPWCMCATMRPW) - 
IGNORE 
/x 

Job control language statements: 

• STEPCAT DD, which makes the user catalog, USERCAT1, and the 

master catalog, AMASTCAT, available for the step. These 
catalogs must be available for the catalog to be reset and 
for the work file to be defined, respectively. Note that, 
when the work file is to be defined in the master catalog, 
the master catalog must be last in the concatenation and the 
catalog name is supplied via the WQRKCAT parameter. > 

• IDCUT1 DD, which identifies the data set to be used for the 
work file. 

• CRAV0L1 DD, which identifies and allocates a volume whose 
catalog recovery area is to be used to reset the catalog. 

• CRAV0L2 DD, which identifies and allocates a volume whose 
catalog recovery area may change as a result of resetting 
the catalog recovery area on volume VSER01. This volume is 
not reset in the catalog. 

• DDCAT DD, which allocates the catalog to be reset. 

The RESETCAT command causes catalog USERCAT1 to be reset from 

the catalog recovery area on VSER01. The RESETCAT command f s 

parameters are: 

• CATALOG, which identifies the catalog to be reset. The 
master password of the catalog is required to update the 
catalog. The DD statement for the catalog is also 
identified. 

• CRAFILES, which specifies a list of DD statements that 
identify the volumes to be used to reset the catalog. ALL 
specifies that the catalog records in the CRA on the volume 
specified by the CRAV0L1 DD statement are to be reset (in 
the catalog). NONE allows the CRAV0L2 DD statement to be 
specified for a CRA volume that is not to be used for reset, 
but that may be needed as a result of the reset (for 
example, a multivolume data set resides on a reset volume 

and on a nonreset volume). / 

• WORKCAT, which specifies the name of the catalog in which to 
define the work file. NORKCAT must be specified if the work 
file is to be defined in the master catalog. 
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RESETCAT 

• IGNORE, which specifies that RESETCAT should force the reset 
of the catalog despite certain errors that may be 
encountered during the RESETCAT processing. 


Resetting a Catalog: Example 2 

This example illustrates the use of RESETCAT to reset a catalog 
CUSERCAT1) after the volume (VSERQO) on which the catalog 
resides has been restored. The volumes owned by USERCAT1, 
VSER01, and V5ER02 have been determined to be out of 
synchronization with the catalog by running a LISTCRA with the 
COMPARE option for all volumes owned by USERCAT1. 

//RECOVER JOB ... 

//JOBCAT DD DSN=USERCAT2,DISP-OLD 
// DD DSN=USERCAT1,DISP=0LD 

//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=A 

//WORKF DD DSN=WGRKFILE,DISP=0LD,UNIT=CDISK,2), 

// VGL=SER=C333333,333334),AMP='AM0RG 5 

//SYSIN DD X 
RESETCAT - 
CATAL0GCUSERCAT1) - 

CRAVOLSC(VSER01 3330-1)(VSER02 333Q-1)) - 
WORKFILECWORKF/WRKPSW) - 
N0IGN0RE 
/X 

Job control language statements: 

• JOBCAT DD, which makes the user catalogs USERCAT2 and 
USERCAT1 available for the job. These catalogs must be 
available for the work file to be defined and for the 
catalog to be reset, respectively. 

• WORKF DD, which identifies the data set to be used for the 
work file. 

Note: All other required volumes will be dynamically 

allocated by RESETCAT. 

The RESETCAT command causes catalog USERCAT1 to be reset from 
the catalog recovery areas on VSERG1 and VSER02. The RESETCAT 
parameters are: 

• CATALOG, which identifies the catalog to be reset. 

• CRAVOLS, which specifies a list of volumes and their device 
types to be used to reset the catalog. 

• WORKFILE, which specifies the DD statement for the work file 
and a password to be used as the work file*s master 
password. 

• N0IGN0RE, which specifies that RESETCAT should not force the 
reset of the catalog if certain errors are encountered. 
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RESETCAT 


Resetting a Catalog: Example 3 

This three part example illustrates the use of RESETCAT to reset 
a catalog (USERCAT1 on volume VSEROO) that must be reallocated 
on a different volume (VSER03). Such a situation may occur when 
irreparable physical damage has occurred to the catalog. In 
this example, the catalog recovery area for the damaged catalog 
volume is assumed to be accessible and valid and thus included 
for reset in the newly defined catalog. Note that the newly 
defined catalog bears the same name as the damaged catalog. The 
other volumes owned by USERCAT1 are VSER01 and VSER02. The 
catalog is first disconnected, then redefined. 

//DISC JOB ... 

//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYS0UT=A 

//STEPCAT DD DSN=USERCAT1,DISP=0LD 

//SYSIN DD * 

EXPORT USERCAT1 DISCONNECT 

//STEP2 EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=A 

//UCATDD DD VOL=SER=VSER03,UNIT=DISK,DISP=0LD 
//CRAV0L1 DD VQL=SER=VSER01,UNIT=DISK,DISP=GLD 
//CRAV0L2 DD V0L=SER=VSER02,UNIT=DISK,DISP=0LD 
//SYSIN DD x 
DEFINE UCAT - 

(NAME (USERCAT1) FILECUCATDD) VQLCVSERQ3) - 
RECOVERABLE CYLC20 1)) - 
DATACCYLC10 1)) INDEXCCYL(1)) 


//STEP3 

EXEC 

PGM=IDCAMS 

//SYSPRINT 

DD 

SYS0UT=A 

//STEPCAT 

DD 

DSN=USERCAT1,DISP=0LD 

// 

DD 

DSN=AMASTCAT,DISP=0LD 

//IDCUT1 

DD 

DSN=WORKFILE,DISP=OLD,UNIT=DISK, 

// 

V0L = 

SER=333333,AMP= *AMORG* 

//SYSIN 

DD 

* 


RESETCAT - 

CATALOG(USERCATl) - 
WORKCAT(AMASTCAT) - 

CRAVOLSC(VSEROO 3330KVSER01 3330-1)(VSER02 3330-1)) 
/x 

STEP1: The user catalog, USERCAT1, is disconnected from the 

system by using the EXPORT command. 

STEP2: The user catalog, USERCAT1, is redefined on the volume 

VSER03. 

STEPS? The user catalog USERCAT1 is reset from the previous 

catalog f s owned volumes. 

Job control language statements: 

• STEPCAT DD, which makes the user catalog, USERCAT1, and the 
master catalog, AMASTCAT, available for the step. These 
catalogs must be available for the catalog to be reset, and 
for the work file to be defined, respectively. 

• IDCUT1 DD, which identifies the data set to be used for the 
work file. 
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RESETCAT 


The RESETCAT command causes the redefined catalog USERCAT1 to be 
reset from the catalog recovery areas on volumes VSEROQ, VSER01, 
and VSER02. The RESETCAT command f s parameters are: 

• CATALOG, which identifies the catalog to be reset. 

• WORKCAT, which specifies the name of the catalog in which to 
define the work file. WORKCAT must be specified if the work 
file is to be defined in the master catalog. 

• CRAVOLS, which specifies a list of volumes and their device 
types to be used to reset the catalog. 
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VERIFY 

YEB1EY 


The VERIFY command causes a catalog to correctly reflect the end 
of a data set after an error has occurred while closing a VSAM 
data set. The error may have caused the catalog to be 
incorrect. 

The format of the VERIFY command is: 


VERIFY 


C FIL E C ddnama C /jE&a g &a n d 3) I 
DAT aset ( an lcypai ri s t £ Pit sm Q td 1 )} 


VERIFY can be abbreviated: VFY 


VERIFY PARAMETERS 


Required Parameters 


FI LE (ddnams E / j s a s sm n d 3) 

ddname specifies the name of a DD statement that identifies 
the cluster or alternate index to be verified. For further 
information, see "Using VERIFY to Synchronize Values" in 

p .assnQiid 

is the control or master password of a 
password-protected object (RACF: The control or alter 
RACF authority to the object is required), or is the 
master password of the object's password-protected 
catalog (RACF: The alter RACF authority to the 
catalog is required). 

DAT ASET (c /jS ^ SSkiS SL Ui 3) 

specifies the name and password of the object to be 
verified. If DATASET is coded, the object is dynamically 
allocated. 

gassward 

is the control or master password of a 
password-protected object (RACF: The control or alter 
RACF authority to the object is required), or is the 
master password of the object's password-protected 
catalog (RACF: The alter RACF authority to the 
catalog is required). 

Abbreviation: DS 

The VERIFY command can be used following a system failure that 
caused a component opened for update processing to be improperly 
closed. It can also be used to verify an entry-sequenced data 
set defined with REUSE that was open in create mode when the 
system failure occurred. 

Note: When sharing data sets between different processors, it 

is recommended that you run VERIFY as the first step of a job 
stream to prevent job termination caused by an open ACB error 
code, if the other processor already has the data set open. 
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VERIFY 


VERIFY EXAMPLE 

c 

Upgrading a Data Set's End-of-File Information: Example 

When a data set that was improperly closed (that is, closed as a 
result of system failure) is opened/ the VSAM OPEN routines set 
a return code to indicate that the data set's cataloged 
information might not be accurate. The user can upgrade the end 
of data (EOD) and end of key range (EOKR) information (so that 
it is accurate when the data set is next opened) by closing the 
data set 1 and issuing the VERIFY command: 

//VERIFY JOB ... 

//JOBCAT DD DSNAME=D27UCAT1,DISP=SHR 

//FIXEOD EXEC PGM=IDCAMS 

//SYSPRINT DD SYS0UT=A 


//SYSIN 

DD X 



LISTCAT 

ENTRIESCFAROUT) - 
ALL 


VERIFY 

DATASETC FAROUT) 

/X 

LISTCAT 

ENTRIESC FAROUT) - 
ALL 


< 


The first LISTCAT command lists the data set's cataloged 
information, showing the data set's parameters as they were when 
the data set was last closed properly. 

The VERIFY command updates the data set's cataloged information 
to show the data set's real EOD and EOKR values. 

The second LISTCAT command lists the data set's cataloged 
information again. This time, the EOD and EOKR information show 
the point at which processing stopped due to system failure. 

This information should help the user determine how much data 
was added correctly before the system failed. 

Note: VERIFY will only update the high-used RBA fields for the 
data set, and not any record counts. 

See Appendix A, "Interpreting LISTCAT Output Listings" on 
page 256, for details on the order in which catalog records are 
to be listed and the meanings of the listed records. 


When the data set is opened (first OPEN after system 
failure), VSAM OPEN sets a "data set improperly closed" 
return code. When the data set is closed properly, VSAM 
CLOSE resets the "data set improperly closed 1 * indicator but 
does not upgrade erroneous catalog information that resulted 
from the system failure. Subsequently, when the data set is 
next opened, its EOD and EOKR information might still be 
erroneous (until VERIFY is issued to correct it), but VSAM 
OPEN sets the "data set opened correctly" return code. 
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The various LISTCAT command options allow you to select the 
LISTCAT output that gives you the information you want. This 
appendix provides information on the structure of LISTCAT output 
when you specify certain options. It also lists and describes 
fields that can be printed for each type of catalog entry. 

Each listed entry is identified by its type (that is, cluster, 
non-VSAM, data, and so forth) and by its entryname. Entries are 
listed in alphabetic order of the entrynames, except when the 
ENTRIES parameter is used. The entries are then listed in the 
order in which they are specified in the ENTRIES parameter. 

An entry that has associated entries is immediately followed by 
the listing of each associated entry. That is, a cluster f s data 
component (and, if the cluster is key-sequenced, its index 
component) is listed immediately following the cluster. If type 
options (CLUSTER, DATA, SPACE, etc.) have been specified or a 
generic entryname list was specified, this excludes the 
associated entry. 

This appendix is organized in three parts; 

• "LISTCAT Output Keywords" lists all field names that can be 
listed for each type of entry. 

• "Description of Keyword Fields" describes each field name 
within a group of related field names. 

• "Examples of LISTCAT Output Listings" describes and 
illustrates the LISTCAT output that results when various 
LISTCAT options are specified. 


This section lists the field names associated with each type of 
catalog entry. Each field name is followed by an abbreviation 
that points to a group of related field descriptions in the next 
section. Keywords are listed in alphabetic order, not in the 
order of appearance in the LISTCAT output. 

The group names and abbreviations are: 

Abbreviations Group Names 

ALC allocation group 

ASN associations group 

ATT attributes group 

DSP data space group 

GDG generation data group base entry, special fields 

NVS non-VSAM entry, special field 

HIS history group 


$ "\ 
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Abbreviations 

PRT 

STA 

VLS 

VOL 


Group Names 
protection group 
statistics group 
volumes group 

volume entry, special fields 


Alias Entry Keywords 


ASSOCIATIONS (ASN) 
entrvname (HIS) 
HISTORY (HIS) 
RCVY-CI (HIS) 
RCVY-DEVT (HIS) 
RCVY-VOL (HIS) 
RELEASE (HIS) 


Alternate-Index Entry Keywords 

ASSOCIATIONS (ASN) 
ATTEMPTS (PRT) 
ATTRIBUTES (ATT) 
CLUSTER (ASN) 

CODE (PRT) 
CONTROLPW (PRT) 
DATA (ASN) 
e ntr y pame (HIS) 
HISTORY (HIS) 
CREATION (HIS) 
EXPIRATION (HIS) 
OWNER-IDENT(HIS) 
RCVY-CI (HIS) 
RCVY-DEVT (HIS) 
RCVY-VOL (HIS) 
RELEASE (HIS) 
INDEX (ASN) 
MASTERPW (PRT) 
NOUPGRADE (ATT) 
PATH (ASN) 
PROTECTION (PRT) 
RACF (PRT) 

READPW (PRT) 
UPDATEPW (PRT) 
UPGRADE (ATT) 

USAR (PRT) 

USVR (PRT) 


Cluster Entry Keywords 

AIX (ASN) 

ASSOCIATIONS (ASN) 
ATTEMPTS (PRT) 

CODE (PRT) 

CONTROLPW (PRT) 

DATA (ASN) 
entrvname (HIS) 
HISTORY (HIS) 
CREATION (HIS) 
EXPIRATION (HIS) 
OWNER-IDENT (HIS) 
RCVY-CI (HIS) 
RCVY-DEVT (HIS) 
RCVY-VOL (HIS) 
RELEASE (HIS) 
INDEX (ASN) 

MASTERPW (PRT) 

PATH (ASN) 
PROTECTION (PRT) 
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RACF (PRT) 
READPW (PRT) 
UPDATEPW (PRT) 
USAR CPRT) 

USVR (PRT) 


Data Entry Keywords 


ALLOCATION (ALC) 
atv ra«KM 

ASSOCIATIONS (ASN) 
ATTEMPTS (PRT) 
ATTRIBUTES (ATT) 
AV6LRECL (ATT) 
AXRKP (ATT) 

BIND (ATT) 

BUFSPACE (ATT) 
BYTES/TRACK (VLS) 
CI/CA (ATT) 

CISIZE (ATT) 

CLUSTER (ASN) 

CODE (PRT) 

CONTROLPW (PRT) 
CYLFAULT (ATT) 
DEVTYPE (VLS) 
DSTGWAIT (ATT) 
ept-cyo am e (HIS) 
ERASE (ATT) 

EXCPEXIT (ATT) 

cyppq fCTAl 

EXTENT-NUMBER (VLS) 
EXTENT-TYPE (VLS) 
EXTENTS (STA) 
EXTENTS (VLS) 
HIGH-CCHH (VLS) 
HIGH-RBA (VLS) 
LOW-CCHH (VLS) 
LOW-RBA (VLS) 
TRACKS (VLS) 
FREESPACE-SCI (STA) 
FREESPACE-/JCA (STA) 
FREESPC-BYTES (STA) 
HIGH-KEY (VLS) 
HI-KEY-RBA (VLS) 
HISTORY (HIS) 
CREATION (HIS) 
EXPIRATION (HIS) 
OWNER-IDENT (HIS) 
RCVY-CI (HIS) 
RCVY-DEVT (HIS) 
RCVY-VOL (HIS) 
RELEASE (HIS) 
IMBED (ATT) 

INDEX (ASN) 
INH-UPDATE (ATT) 
INDEXED (ATT) 

KEYLEN (ATT) 

LOW-KEY (VLS) 
MASTERPW (PRT) 
MAXLRECL (ATT) 
MAXRECS (ATT) 
NOERASE (ATT) 
NOIMBED (ATT) 
NONINDEXED (ATT) 
NOREPLICAT (ATT) 
NOREUSE (ATT) 
NONSPANNED (ATT) 
NOSWAP (ATT) 
NOTRKOVFL (ATT) 
NONUNIQKEY (ATT) 
NOTUSABLE (ATT) 
NOWRITECHK (ATT) 
NUMBERED (ATT) 
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ORDERED (ATT) 

PGSPC (ASN) 

PHYRECS/TRK (VLS) 
PHYREC/SIZE (VLS) 
PROTECTION (PRT) 

RACF (PRT) 

HI-ALLOC-RBA (ALC) 
HI-USED-RBA (ALC) 
HI-ALLOC-RBA (VLS) 
HI-USED-RBA (VLS) 
READPW (PRT) 

RECOVERY (ATT) 
REC-DELETED (STA) 
REC-INSERTED (STA) 
REC-RETRIEVED (STA) 
REC-TOTAL (STA) 
REC-UPDATED (STA) 
RECORDS/CI (ATT) 
REPLICATE (ATT) 

RKP (ATT) 

REUSE (ATT) 

RECVABLE (ATT) 

SHROPTNS (ATT) 
SPACE-PRI (ALC) 
SPACE-SEC (ALC) 
SPACE-TYPE (ALC) 

SPEED (ATT) 

SPLITS-CA (STA) 
SPLITS-CI (STA) 

SPANNED (ATT) 
STATISTICS (STA) 
SUBALLOC (ATT) 

SWAP (ATT) 

SYSTEM-TIMESTAMP (STA) 
TEMP-EXP (ATT) 
TRACKS/CA (VLS) 

TRKOVFL (ATT) 

UNORDERED (ATT) 

UNIQUE (ATT) 

UNIQUEKEY (ATT) 
UPDATEPW (PRT) 

USAR (PRT) 

USVR (PRT) 

VOLFLAG (VLS) 

VOLSER (VLS) 

VOLUMES (VLS) 
WRITECHECK (ATT) 


Index Entry Keywords 


ALLOCATION (ALC) 

AIX (ASN) 

ASSOCIATIONS (ASN) 
ATTEMPTS (PRT) 
ATTRIBUTES (ATT) 
AVGLRECL (ATT) 

BIND (ATT) 

BUFSPACE (ATT) 

CI/CA (ATT) 

CISIZE (ATT) 

CLUSTER (ASN) 

CODE (PRT) 

CONTROLPW (PRT) 
CYLFAULT (ATT) 
DEVTYPE (VLS) 
DSTGWAIT (ATT) 
.en trynane (HIS) 
ERASE (ATT) 

EXCPEXIT (ATT) 
EXTENTS (STA) 
EXTENT-NUMBER (VLS) 
EXTENT-TYPE (VLS) 
EXTENTS (VLS) 
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HIGH-CCHH (VLSI 
HIGH-RBA (VLS) 
LOW-CCHH (VLS) 
LOW-RBA (VLS) 

TRACKS (VLS) 
FREESPACE-SCI (STA) 
FREESPACE-5JCA (STA) 
FREESPC-BYTES (STA) 
HIGH-KEY (VLS) 

HISTORY (HIS) 

CREATION (HIS) 
EXPIRATION (HIS) 
OWNER-IDENT (HIS) 
RCVY-CI (HIS) 
RCVY-DEVT (HIS) 
RCVY-VOL (HIS) 
RELEASE (HIS) 

IMBED (ATT) 

INDEX (STA) 

ENTRIES/SECT (STA) 
HI-LEVEL-RBA (STA) 
LEVELS (STA) 
SEQ-SET-RBA (STA) 
INH-UPDATE (ATT) 

KEYLEN (ATT) 

LOW-KEY (VLS) 

MASTERPW (PRT) 

MAXLRECL (ATT) 

NOERASE (ATT) 

NOIMBED (ATT) 
NOREPLICAT (ATT) 
NOREUSE (ATT) 

EXCPS (STA) 

EXTENTS (STA) 

NOTUSABLE (ATT) 
NOWRITECHK (ATT) 
ORDERED (ATT) 
PHYRECS/TRK (VLS) 
PHYREC-SIZE (VLS) 
PROTECTION (PRT) 

RACF (PRT) 

HI-ALLOC-RBA (ALC) 
HI-USED-RBA (ALC) 
HI-ALLOC-RBA (VLS) 
HI-USED-RBA (VLS) 
RECOVERY (ATT) 

READPW (PRT) 
REC-DELETED (STA) 
REC-INSERTED (STA) 
REC-RETRIEVED (STA) 
REC-TOTAL (STA) 
REC-UPDATED (STA) 
REPLICATE (ATT) 

RKP (ATT) 

REUSE (ATT) 

SHROPTNS (ATT) 
SPACE-PRI (ALC) 
SPACE-SEC (ALC) 
SPACE-TYPE (ALC) 

SPEED (ATT) 

SPLITS-CA (STA) 
SPLITS-CI (STA) 
STATISTICS (STA) 
SUBALLOC (ATT) 
SYSTEM-TIMESTAMP (STA) 
TEMP-EXP (ATT) 
TRACKS/CA (VLS) 
UNORDERED (ATT) 

UNIQUE (ATT) 

UPDATEPW (PRT) 

USAR (PRT) 

USVR (PRT) 

VOLFLAG (VLS) 

VOLSER (VLS) 
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VOLUME (VLSI 
WRITECHECK (ATT) 


Generation Data Group Base Entry Keywords 

ASSOCIATIONS (ASN) 
ATTRIBUTES (GDG) 

EMPTY (GDG) 

LIMIT (GDG) 

NOEMPTY (GDG) 
NOSCRATCH (GDG) 
SCRATCH (GDG) 
entrvname (HIS) 
HISTORY (HIS) 

CREATION (HIS) 
EXPIRATION (HIS) 
OWNER-IDENT (HIS) 
RCVY-CI (HIS) 
RCVY-DEVT (HIS) 
RCVY-VOL (HIS) 
RELEASE (HIS) 
NONVSAM (ASN) 


Non-VSAM Entry Keywords 

ALIAS (ASN) 
ASSOCIATIONS (ASN) 
DEVTYPE(VLS) 
entryneme (His) 
FSEQN (NVS) 

HISTORY (HIS) 
CREATION (HIS) 
EXPIRATION (HIS) 
OWNER-IDENT (HIS) 
RCVY-CI (HIS) 
RCVY-DEVT (HIS) 
RCVY-VOL (HIS) 
RELEASE (HIS) 
VOLSER(VLS) 


Page Space Entry Keywords 

ASSOCIATIONS (ASN) 
ATTEMPTS (PRT) 

CODE (PRT) 

CONTROLPW (PRT) 

DATA (ASN) 

Antcyn^me. (HIS) 
HISTORY (HIS) 
CREATION (HIS) 
EXPIRATION (HIS) 
OWNER-IDENT (HIS) 
RCVY-CI (HIS) 
RCVY-DEVT (HIS) 
RCVY-VOL (HIS) 
RELEASE (HIS) 
INDEX (ASN) 

MASTERPW (PRT) 
PROTECTION (PRT) 
RACF (PRT) 

READPW (PRT) 
UPDATEPW (PRT) 

USAR (PRT) 

USVR (PRT) 
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Path Entry Keywords 


AIX (ASN) 

ASSOCIATIONS (ASN) 
ATTEMPTS (PRT) 
ATTRIBUTES (ATT) 
CLUSTER (ASN) 

CODE (PRT) 

CONTROLPW (PRT) 

DATA (ASN) 
entrvname (HIS) 
HISTORY (HIS) 
CREATION (HIS) 
EXPIRATION (HIS) 
3WNER-IDENT (HIS) 
RCVY-CI (HIS) 
RCVY-DEVT (HIS) 
RCVY-VOL (HIS) 
RELEASE (HIS) 
INDEX (ASN) 

MASTERPW (PRT) 
NOUPDATE (ATT) 
PROTECTION (PRT) 
RACF (PRT) 

READPW (PRT) 

UPDATE (ATT) 
UPDATEPW (PRT) 

USAR (PRT) 

USVR (PRT) 


User Catalog Entry Keywords 

ALIAS (ASN) 
ASSOCIATIONS (ASN) 
DEVTYPE(VLS) 
entrvname (HIS) 
HISTORY (HIS) 
RCVY-CI (HIS) 
RCVY-DEVT (HIS) 
RCVY-VOL (HIS) 
RELEASE (HIS) 
VOLFLAG (VLS) 
VOLSER (VLS) 


Volume Entry Keywords 

ATTRIBUTES (DSP) 
AUTOMATIC (DSP) 
EXPLICIT (DSP) 
MASTERCAT (DSP) 
SUBALLOC (DSP) 

UNIQUE (DSP) 

USERCAT (DSP) 
BYTES/TRK (VOL) 
CHARACTERISTICS (VOL) 
CYLS/VOL (VOL) 
DATASET-DIRECTORY (DSP) 
ATTRIBUTES (DSP) 

DSN (DSP) 

EXTENTS (DSP) 

DATASETS (DSP) 
DATASETS-ON-VOL (VOL) 
DATASPACE (DSP) 
DATASPCS-ON-VOL (VOL) 
DEVTYPE (VOL) 
EXTENT-DESCRIPTOR (DSP) 
BEG-CCHH (DSP) 
SPACE-MAP (DSP) 
TRACKS-TOTAL (DSP) 
TRACKS-USED (DSP) 
EXTENTS (DSP) 
FORMAT-l-DSCB (DSP) 
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CCHHR (DSP) 
TIMESTAMP (DSP) 
MAX-PHYREC-SZ (VOL) 
MAX-EXT/ALLOC (VOL) 
HISTORY (HIS) 
RCVY-CI (HIS) 
RCVY-DEVT (HIS) 
RCVY-VOL (HIS) 
RELEASE (HIS) 

SEC ALLOC (DSP) 
TRKS/CYL (VOL) 

TYPE (DSP) 

CYLINDER (DSP) 
TRACK (DSP) 


y- p .L u me..g.en; U 1.n umbe r (HIS) 


VOLUME-TIMESTAMP (VOL) 


DESCRIPTION OF KEYWORD FIELDS 

This section contains a description of each field name. The 
field names are in the following groups of related information: 

Abbreviations Group Names 

ALC allocation group 

ASN associations group 

ATT attributes group 

DSP data space group 

GDG generation data group base entry, special fields 

NVS non-VSAM entry, special field 

HIS history group 

PRT protection group 

STA statistics group 

VLS volumes group 

VOL volume entry, special fields 

Groups are in alphabetic order. Field names within each group 
are in alphabetic order, not the order of appearance in the 
listed entry. 


ALC: ALLOCATION GROUP 

The fields in this group describe the space allocated to the 
data or index component defined by the entry. 

HI-ALLOC-RBA —The highest RBA (plus 1) available within 
allocated space to store data. 

HI-USED-RBA —The highest RBA (plus 1) within allocated space 
that actually contains data. 

SPACE-PRI —Gives the number of units (indicated under TYPE) 
of space allocated to the data or index component when the 
cluster (that is, its data or index component) was defined. 
This amount of space is to be allocated whenever a data 
component (or key range within it, and its associated 
sequence set, if IMBED is an attribute of the cluster) is 
extended onto a candidate volume. 

SPACE-SEC —Gives the number of units (indicated under TYPE) 
of space to be allocated whenever a data set (or key range 
within it) is extended on the same volume. 
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SPACE-TYPE—Indicates the unit of space allocation: 


CYLINDER—Cylinders 
TRACK—Tracks 


(f 


ASMS ASSOCIATIONS GROUP 

This group lists the type, such as cluster or data, and 
entrynames of the objects associated with the present entry. A 
cluster or alternate index entry will indicate its associated 
path entries and data and index (if a key-sequenced data set) 
entries. Similarly, an index or data entry will indicate its 
associated cluster or the alternate index of which it is a 
component. 

• An alias entry points to: 

— Its associated non-VSAM data set entry. 

— A user catalog entry. (All alias entries for a non-VSAM 
data set entry are chained together, as are alias 
entries for a user catalog entry.) 

• An alternate index entry points to: 

— Its associated data and index entries. 

— Its base cluster's cluster entry. 

— Each associated path entry. 

• An alternate index's data entry points to: 

— Its associated alternate index entry. 

• An alternate index's index entry points to: 

— Its associated alternate index entry. 

• A cluster entry points to: 

— Its associated data entry. 

— Each associated path entry. 

— For a key-sequenced cluster, its associated index entry. 

— For a cluster with alternate indexes, each associated 
alternate index entry. 

• A cluster's data entry points to: 

— Its associated cluster entry. 

• A cluster's index entry points to: 

— Its associated cluster entry. 

• A generation data group base entry points to: 

— Its associated non-VSAM data set entries. 

• A non-VSAM data set entry points to: 

— Its associated alias entry. 

— Its associated generation data group (for a G0000V00 

non-VSAM). * 

V 
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• A page space entry points to: 

— Its associated data entry. (The page space is cataloged 
as an entry-sequenced cluster with a cluster entry and 
an associated data entry.) 

• A path entry (that establishes the connection between a base 
cluster and an alternate index) points to: 

— Its associated alternate index entry# and the alternate 
index’s associated data and index entries. 

— The data entry of its associated base cluster. 

— For a key-sequenced base cluster# the index entry of its 
associated base cluster. 

• Path entry (that is an alias for a cluster entry) points to: 
— Its associated base cluster entry. 

— The data entry of its associated base cluster. 

— For a key-sequenced cluster# the index entry of its 
associated base cluster. 

• A user catalog entry points to: 

— Its associated alias entry. 

AIX—Identifies an alternate index entry. 

ALIAS—Identifies an alias entry. 

CLUSTER—Identifies a cluster entry. 

DATA—Identifies a data entry. 

GDG—Identifies a generation data group (GDG) base entry. 

INDEX—Identifies an index entry. 

NONVSAM—Identifies a non-VSAM data set entry. 

PGSPC—Identifies a page space entry. 

PATH—Identifies a path entry. 

UCAT—Identifies a user catalog entry. 


ATT: ATTRIBUTES GROUP 

The fields in this group describe the miscellaneous attributes 
of the entry. See the DEFINE command for further discussion of 
most of these attributes. 

AVGLRECL—The average length of data records. AVGLRECL equals 
MAXLRECL when the records are fixed length. 

AXRKP—Indicates# for an alternate index# the offset# from the 
beginning of the base cluster’s data record, at which the 
alternate-key field begins. 

BIND—The component is staged from mass storage to a direct 
access storage staging drive when it is opened# and it is 
retained (bound) in direct access storage until it is closed. 

BUFSPACE—The minimum buffer space in virtual storage to be 
g provided by a processing program. 

CI/CA—The number of control intervals per control area. 

CISIZE—The size of a control interval. 
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CYLFAULT—The component is not staged from mass storage to a 
direct access storage staging drive when it is opened, but data 
from it is staged as the data is needed. 

DSTGWAIT—The component is destaged from direct access storage 
to mass storage before VSAM returns control to the program that 
is closing it. 

ERASE—Records are to be erased (set to binary zeros) when 
deleted. 

EXCPEXZT—The name of the objects exception exit routine. 

IMBED—The sequence-set index record is stored along with its 
associated data control area. 

INH-UPDATE—The data component cannot be updated. Either the 
data component was exported with INHIBITSQURCE specified, or its 
entry was modified by way of ALTER, with INHIBIT specified. 

INDEXED—The data component has an index; it is key sequenced. 

KEYLEN—The length of the key field in a data record. 

MAXLRECL—The maximum length of data or index records. AVGLRECL 
equals MAXLRECL when the records are fixed length. 

MAXRECS—Identifies the highest possible valid relative record 
number, for a relative record data set. This value is 
calculated as follows: 

2 32 /CISIZE x number of records slots per control interval. 

NOERASE—Records are not to be erased (set to binary 0's) when 
deleted. 

NOIMBED—The sequence-set index record is not stored along with 
its associated data control area. 

NONINDEXED—The data component has no index; it is entry 
sequenced. 

NONSPANNED—Data records cannot span control intervals. 

NONUNIQKEY—Indicates, for an alternate index, that more than 
one data record in the base cluster can contain the same 
alternate-key value. 

NOREPLICAT—Index records are not replicated. 

NOREUSE—The data set cannot be reused. 

NOSWAP—The page space is a conventional page space and cannot 
be used as a high speed swap data set. 

NOTRKOVFL—The physical blocks of a page space data set cannot 
span a track boundary. 

NOUPDATE—When the path is opened for processing, its associated 
base cluster is opened but the base cluster's upgrade set is not 
opened. 

NOUPGRADE—The alternate index is not upgraded unless it is 
opened and being used to access the base cluster's data records. 

NOTUSABLE—The entry is not usable because (1) the catalog could 
not be correctly recovered by RESETCAT, or (2) a DELETE SPACE 
FORCE was issued for a volume(s) in the entry's volume list. 

NOWRITECHK—Write operations are not checked for correctness. 

NUMBERED—The cluster is a relative record data set. 
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ORDERED—Volumes are used for space allocation in the order they 
were specified when the cluster was defined. 

RECOVERY—A temporary CLOSE is issued as each control area of 
the data set is loaded, so the whole data set won f t have to be 
reloaded if a serious error occurs during loading. 

RECORDS/CI—Specifies the number of records, or slots, in each 
control interval of a relative record data set. 

RECVABLE—This attribute is set in the data entry of a 
recoverable catalog, and each of the catalog's volumes contains 
a catalog recovery area. 

REPLICATE—Index records are replicated (that is, each is 
duplicated around a track of the index's direct access device). 

REUSE—The data set can be reused (that is, its contents are 
temporary and its high-used RBA can be reset to 0 when it is 
opened). 

RKP—The relative key position—the displacement from the 
beginning of a data record to its key field. 

SHROPTNS—( n,m) The numbers n and m identify the types of 
sharing permitted. See SHAREOPTIONS in the DEFINE CLUSTER 
section for more details. 

SPANNED—Data records can be longer than control interval 
length, and can cross, or span, control interval boundaries. 

SPEED—CLOSE is not issued until the data set has been loaded. 

SUBALLOC—More than one VSAM cluster can share the data space. 

A VSAM catalog might also occupy the data space. 

SWAP—The page space is a high speed swap data set used by 
Auxiliary Storage Management during a swap operation to store 
and retrieve the set of LSQA pages owned by an address space. 

TEMP-EXP—The data component was temporarily exported. 

TRKOVFL—The physical blocks of a page space data set can span a 
track boundary. 

UNIQUE—Only one VSAM cluster or catalog can occupy the data 
space—the cluster or catalog is unique. 

UNIQUEKEY—Indicates, for an alternate index, that the 
alternate-key value identifies one, and only one, data record in 
the base cluster. 

UNORDERED—Volumes specified when the cluster was defined can be 
used for space allocation in any order. 

UPDATE—When the path is opened, the upgrade set's alternate 
indexes (associated with the path's base cluster) are also 
opened and are updated when the base cluster's contents change. 

UPGRADE—When the alternate index's base cluster is opened, the 
alternate index is also opened and will be updated to reflect 
any changes to the base cluster's contents. 

WRITECHECK—Write operations are checked for correctness. 
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DSP: DATA SPACE GROUP 


zf . 

The fields in this group are included by LISTCAT, as part of a [ : 

volume entry, for each data space on the volume. If a volume 
contains no data spaces, it is a candidate volume. 

ATTRIBUTES —Describes the attributes of the data space. 

AUTOMATIC —The data space was created automatically by a 
secondary allocation operation. If a VSAM cluster must be 
given additional space on a volume and all existing data 
spaces are full, an existing data space will be extended, or 
a new one allocated on the volume, using catalog DADSM. A 
new data space so allocated is known as an implicit or 
automatic data space. 

EXPLICIT —The data space was created explicitly by a DEFINE 
MASTERCATALOG or USERCATALOG command, or a DEFINE 
ALTERNATEINDEX or DEFINE CLUSTER command with the UNIQUE 
attribute specified or by a DEFINE SPACE command. 

MASTERCAT —The data space contains the master catalog. 

SUBALLOC —The data space might contain several VSAM 
clusters. 

USERCAT —The data space contains a user catalog. 

UNIQUE —The data space contains a single (unique) VSAM 
cluster or catalog. 

DATASET DIRECTORY—Lists the VSAM data sets that can be stored 
(see CANDIDATE below) or actually are stored (in whole or in 
part) in the data space. 

ATTRIBUTES —Describes the relation between the named data ^ 

set and the data space. 

v,_.-y 7 

CANDIDATE —The volume is a candidate for storing the 
data set 

(NULL) —The data set is stored (in whole or in part) in 
the data space 

DSN —The data set name of the object that can be stored or 
is stored on the volume. 

EXTENTS —The number of data set extents for the data set 
within the data space. 

DATASETS —The number of VSAM data sets stored (in whole or in 
part) in the data space. (The number includes data sets for 
which the volume is a candidate.) 

EXTENT-DESCRIPTOR —Describes the data space extent. 

BEG-CCHH —The device address (that is, CC = cylinder and HH 
~ track) of the extent. 

SPACE-MAP—A hexadecimal number that tells what tracks are 
used and what tracks are free in the extent. The number 
consists of one or more run length codes (RLCs). The first 
RLC gives the number of contiguous used tracks, starting at 
the beginning of the extent; if all the tracks in the extent 
are used, there is only one RLC. The second RLC gives the 
number of contiguous free tracks, beyond the used tracks. A 
third RLC gives used tracks again, a fourth gives free 
tracks, and so on. 

A 1-byte RLC gives the number of tracks less than or equal r 

to 250; a 3-byte RLC gives the number of tracks greater than f 
250. That is, if the first byte of an RLC is X^A* (250) or 
less, it is the only byte of the RLC and gives the number of 
tracks. If the first byte of an RLC is X^B 1 (251) or more. 
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the byte is followed by two more bytes that give the number 
of tracks (the first byte indicates merely to look at the 
next two bytes). 

TRACKS-TOTAL—Allocated to the data space altogether. 

TRACKS-USED—Used to store data. 

EXTENTS—The number of data space extents in the data space. 

FQRMAT-l-DSCB—Identifies the format-1 DSCB that describes the 
data space. 

CCHHR—The device address (that is, CC = cylinder, HH = 
track, and R = record number) of the DSCB in the VTOC. 

TIMESTAMP—The time the data space was allocated (system 
time-of-day clock value). The DSCB contains the timestamp 
as part of the VSAM-generated name. 

SEC-ALLOC—Gives the number of units (indicated under TYPE) of 
space to be allocated whenever the data space is extended. 

TYPE—Indicates the unit of space allocation: 

CYLINDERS—Cylinders 

TRACK—Tracks 


GDG: GENERATION DATA GROUP BASE ENTRY, SPECIAL FIELDS 

The special fields for a generation data group base entry 
describe attributes of the generation data group. 

ATTRIBUTES 

This field includes the following fields: 

EMPTY 

All generation data sets in the generation data group 
will be uncataloged when the maximum number (given 
under LIMIT) is reached and one more data set is to be 
added to the group. 


LIMIT 

The maximum number of generation data sets allowed in 
the generation data group. 

NOEMPTY 

Only the oldest generation data set in the generation 
data group will be uncataloged when the maximum number 
(given under LIMIT) is reached and one more data set 
is to be added to the group. 

NOSCRATCH 

Generation data sets are not to be scratched (see 
SCRATCH below) when uncataloged. 

SCRATCH 

Generation data sets are to be scratched (that is, the 
DSCB that describes each one is removed from the VTOC 
of the volume on which it resides) when uncataloged. 
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NVS: NON-VSAM ENTRY, SPECIAL FIELD 


The special field for a non-VSAM data set describes a non-VSAM 
data set stored on magnetic tape. 

FSEQN—The sequence number (for the tape volume indicated under 
the "VOLUMES group" keyword VOLSER) of the file in which the 
non-VSAM data set is stored. 


HIS: HISTORY GROUP 


The fields in this group identify the object*s owner, identify 
its catalog recovery volume and release level* and give the 
object f s creation and expiration dates. 

entryname —The name of the cataloged object. The entryname can 
be specified with the ENTRIES parameter of LISTCAT to identify a 
catalog entry. 

HISTORY—This field includes the following fields: 

CREATION—The Julian date (yy.ddd) on which the entry was 
created. This field will always contain 00.000 for a 
non-VSAM data set entry in an OS CVOL. 

EXPIRATION—The Julian date (yy.ddd) after which the entry 
can be deleted without specifying the PURGE parameter in the 
DELETE command. Julian date 99.999 indicates that PURGE is 
always required to delete the object. This field will 
always contain 00.000 for a non-VSAM data set entry in an OS 
CVOL. 

OWNER-IDENT—The identity of the owner of the object 
described by the entry. 

RCVY-CI—If the entry is in a recoverable catalog* this 
field contains the control interval number in the catalog 
recovery area where a duplicate of the entry can be found. 

RCVY-DEVT—If the entry is in a recoverable catalog* this 
field identifies the recovery volume's device type. (See 
the Device Type Translate Table at the end of this section 
for a translation of the hexadecimal device type to its 
equivalent EBCDIC value.) 

RCVY-VOL—If the entry is in a recoverable catalog* this 
field contains the recovery volume's serial number. 

RELEASE—The release of VSAM under which the entry was 
created: 

1 = 0S/VS2 Release 3 and releases preceding Release 3 

2 = QS/VS2 Release 3.6 and any later releases 


PRT: PROTECTION GROUP 

The fields in this group describe how the alternate index* 
cluster* data component* index component* or path defined by the 
entry is password protected or RACF protected. NULL or 
SUPPRESSED might be listed under password protection and YES or 
NO might be listed under RACF protection. 

NULL indicates that the object defined by the entry has no 
passwords. 

SUPP indicates that the master password of neither the catalog 
nor the entry was specified* so authority to list protection 
information is not granted. 

RACF—Indicates whether or not the entry is protected by the 
Resource Access Control Facility. 
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YES—Entry is RACF protected. 

NO—Entry is not RACF protected. 

ATTEMPTS—Gives the number of times the console operator is 
allowed to attempt to enter a correct password. 

CODE—Gives the code used to tell the console operator what 
alternate index, catalog, cluster, path, data component, or 
index component requires him to enter a password. NULL is 
listed under CODE if a code is not used—the object requiring 
the password is identified with its full name. 

CONTROLPW—The control interval password (that is, the password 
for control interval access). NULL indicates no control 
interval password. 

MASTERPW—The master password. 

READPW—The read-only password. NULL indicates no read-only 
password. 

UPDATEPW—The update password. NULL indicates no update 
password. 

USAR—The contents (1 to 255 bytes, in character format) of the 
USAR (usei—security-authorization record). This is the 
information specified in the string subparameter of the AUTH 
subparameter of the DEFINE command. 

USVR—The name of the USVR (usei—security-verification routine) 
which is to be invoked to verify authorization of any access to 
the entry. 


STA: STATISTICS GROUP 

The fields in this group give numbers and percentages that 
indicate how much activity has taken place in the processing of 
a data or index component. The statistics in the catalog are 
updated when the data set is closed. Therefore, if a failure 
occurs during CLOSE, the statistics may not be valid. Because a 
VSAM catalog remains open from job to job, its statistics are 
not updated. 

Statistic values can be any value from a minus to a large 
number, if a failure occurs before or during close processing. 
VERIFY will not correct these statistics. 

FREESPACE-XCI—Percentage of space to be left free in a control 
interval for subsequent processing. 

FREESPACE-XCA—Percentage of control intervals to be left free 
in a control area for subsequent processing. 

FREESPC-BYTES—Actual number of bytes of free space in the total 
amount of space allocated to the data or index component. ^ree 
space in partially used control intervals is not included i 
this statistic. 

INDEX—This field appears only in an index entry. The fields 
under it describe activity in the index component. 

ENTRIES/SECT—The number of entries in each section of 
entries in an index record. 

HI-LEVEL-RBA—The relative byte address (RBA) of the 
highest-level index record. 

LEVELS—The number of levels of records in the index. The 
number is 0 if no records have been loaded into the 
key-sequenced data set to which the index belongs. 
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SEQ-SET-RBA —The RBA, in decimal, of the first sequence-set 
record. The sequence set might be separated from the index 
set by some quantity of RBA space. 

The remaining fields in the statistics group (except for the 
system timestamp field), are updated only when the data set is 
closed. 

EXCPS —EXCP (execute channel program—SVC 0) macro instructions 
issued by VSAM against the data or index component. 

EXTENTS —Extents in the data or index component. 

REC-DELETED —The number of records that have been deleted from 
the data or index component. Statistics for records deleted are 
not maintained when the data set is processed in control 
interval mode. 

REC-INSERTED —For a key-sequenced data set, the number of 
records that have been inserted into the data component before 
the last record; records originally loaded and records added to 
the end are not included in this statistic. For relative record 
data sets, it is the number of records inserted into available 
slots; the number of records originally loaded are included in 
this statistic. Statistics for records inserted are not 
maintained when the data set is processed in control interval 
mode. 

REC-RETRIEVED —The number of records that have been retrieved 
from the data or index component, whether for update or not for 
update. Statistics for records retrieved are not maintained 
when the data set is processed in control interval mode. 

REC-TOTAL —The total number of records actually in the data or 
index component. This statistic is not maintained when the data 
set is processed in control interval mode. 

REC-UPDATED —The number of records that have been retrieved for 
update and rewritten. This value does not reflect those records 
that were deleted, but a record that is updated and then deleted 
is counted in the update statistics. Statistics for records 
updated are not maintained when the data set is processed in 
control interval mode. 

SPLITS-CA —Control area splits. Half the data records in a 
control area were written into a new control area and then were 
deleted from the old control area. 

SPLITS-CI —Control interval splits. Half the data records in a 
control interval were written into a new control interval and 
then were deleted from the old control interval. 

SYSTEM-TIMESTAMP —The time (system time-of-day clock value) the 
data or index component was last closed (after being opened for 
operations that might have changed its contents). 


VLS: VOLUMES GROUP 


The fields in this group identify the volume(s) on which a data 
component, index component, user catalog, or non-VSAM data set 
is stored. It also identifies candidate volume(s) for a data or 
index component. The fields describe the type of volume and 
give, for a data or index component, information about the space 
the object uses on the volume. 

• If an entry-sequenced or relative record cluster f s data 
component has more than one VOLUMES group, each group 
describes the extents that contain data records for the 
cluster on a specific volume. 

• If a key-sequenced cluster f s data component has more than 
one VOLUMES group, each group describes the extents that 
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contain data records for the cluster, or one of its key 
ranges, on a specific volume. 

• If a key-sequenced cluster f s index component has more than 
one VOLUMES group, each group describes the extents that 
contain index records for the cluster, or one of its key 
ranges, on a specific volume. The first VOLUMES group 
describes the extent that contains the high-level index 
records (that is, index records in levels above the sequence 
set level). Each of the next groups describe the extents 
that contain sequence-set index records for the cluster, or 
one of its key ranges, on a specific volume. The index 
component of a key-sequenced data set with the IMBED 
attribute will have a minimum of two volume groups, one for 
the imbedded sequence set, and one for the high-level index. 
The extents for the imbedded sequence set will be the same 
as those for the data component. 

BYTES/TRACK—The number of bytes that VSAM can write on a track 
(listed for page spaces only). 

DEVTYPE—The type of device to which the volume belongs. (See 
the Device Type Translate Table at the end of this section for a 
translation of the hexadecimal device type to its equivalent 
EBCDIC value.) 

EXTENT-NUMBER—The number of extents allocated for the data or 
index component on the volume. 

EXTENT-TYPE—The type of extents* 

00—The extents are contiguous 

40—The extents are not preformatted 

80—A sequence set occupies a track adjacent to a control 
area. 

EXTENTS—Gives the physical and relative byte addresses of each 
extent. 

HIGH-CCHH—The device address (that is, CC = cylinder and HH 
= track) of the end of the extent. 

HXGH-RBA—The RBA (relative byte address), in decimal, of 
the end of the extent. 

LOW-CCHH—The device address (that is, CC = cylinder and HH 
= track) of the beginning of the extent. 

LOW-RBA—The RBA (relative byte address), in decimal, of the 
beginning of the extent. 

TRACKS—The number of tracks in the extent, from low to high 
device addresses. 

HIGH-KEY 2 —For a key-sequenced data set with the KEYRANGE 
attribute, the highest hexadecimal value allowed on the volume 
in the key field of a record in the key range. A maximum of 64 
bytes can appear in HIGH-KEY. 

HI-KEY-RBA 2 —For a key-sequenced data set, the RBA (relative 
byte address), in decimal, of the control interval on the volume 
that contains the highest keyed record in the data set or key 
range. 

LOW-KEY 2 —For a key-sequenced data set with the KEYRANGE 
attribute, the lowest hexadecimal value allowed on the volume in 
the key field of a record in the key range. A maximum of 64 
bytes can appear in LOW-KEY. 


Multiple key ranges may reside on a single volume; the 
volumes group is repeated for each such key range field. 
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PHYRECS/TRK —The number of physical records (of the size 
indicated under PHYRECS-SIZE) that VSAM can write on a track on 
the volume. 

PHYREC-SIZE— The number of bytes that VSAM uses for a physical 
record in the data or index component. 

HI-ALLOC-RBA —The highest RBA (plus 1) available within 
allocated space to store data component* its key range* the 
index component* or the sequence set records of a key range. 

HI-USED-RBA —The highest RBA (plus 1) within allocated space 
that actually contains data component* its key range* the index 
component* or the sequence set records of a key range. 

TRACKS/CA —The number of tracks in a control area in the data 
component. (This value is computed when the entry is defined* 
and reflects the optimum size of the control area for the given 
device type and the nature of the entry—whether indexed* 
nonindexed* or numbered.) For a key-sequenced data set with the 
imbedded attribute* this value includes the sequence set track. 

VOLFLAG —Indicates whether the volume is a candidate volume* the 
first* or a subsequent volume on which data in a given key range 
is stored. 

CANDIDATE —The volume is a candidate for storing the data or 
index component. 

OVERFLOW —The volume is an overflow volume on which data 
records in a key range are stored. The KEYRANGE begins on 
another (PRIME) volume. 

PRIME —The volume is the first volume on which data records 
in a key range are stored. 

VOLSER —The serial number of the volume. 


VOL: VOLUME ENTRY* SPECIAL FIELDS FOR 

The special fields for a volume entry describe the 
characteristics of the space that VSAM uses on the volume. 

volume serial number —The name of the cataloged volume entry. 

The volume serial number can be specified with the ENTRIES 
parameter of LISTCAT to identify the volume entry. 

BYTES/TRK —The number of bytes that VSAM can use on each track 
on the volume. 

CYLS/VOL —The number of cylinders that VSAM can use on the 
volume* including alternate track cylinders. 

DATASETS-ON-VOL —The number of VSAM clusters that reside* in 
whole or in part* on the volume. This includes candidate 
volumes. 

DATASPCS-ON-VOL —The number of VSAM data spaces on the volume. 
Should the number of data spaces be zero* then this is a 
candidate volume only* and the data space group is omitted. 

DEVTYPE —The type of device to which the volume belongs. (See 
the Device Type Translate Table at the end of this section for a 
translation of the hexadecimal device type to its equivalent 
EBCDIC value.) 

MAX-PHYREC-SZ —The size of the largest physical record that VSAM 
can write on the volume. 

MAX-EXT/ALLOC —The maximum number of extents that can be 
allocated per each allocation request for a single data set on 
the volume. 
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TRKS/CYL—The number of tracks in each cylinder on the volume. 


VOLUME-TIMESTAMP— The time (system time-of-day clock value) VSAM 
last changed the contents of the volume. The format-4 DSCB 
contains the timestamp at offset 76 (X'4C'). 


DEVICE TYPE TRANSLATE TABLE 


LISTCAT Code Device Type 


3000 8001 
3010 200C 
3010 200E 
3040 200A 
3050 2006 
3050 2007 
3050 2009 
3050 200B 
3050 200D 
3058 2009 
3080 8001 
30C0 2008 
3200 8003 
3400 8003 


9 TRK TAPE 

3375 

3380 3 

3340 (35M/70M) 

2305-1 

2305-2 

3330 

3350 

3330-1 

3330V 

7 TRK TAPE 
2314/2319 

9 TRK, 6250 BPI TAPE 
9 TRK, 1600 BPI TAPE 


Refer to "Data Area Description of the Unit Control Block (UCB)" 

in System Programming Library! _ Debugging Handbook, Volume 3 for 

additional information on device types. 


3380 models A04, AA4, B04, AD4, BD4, AE4, and BE4. 
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This section illustrates the kind of output you can get when you 
specify LISTCAT parameters. It also describes the job control 
language you can specify and the output messages you receive 
when the LISTCAT procedure executes successfully. 


JOB CONTROL LANGUAGE (JCL) FOR LISTCAT JOBS 


The job control language (JCL) statements that can be used to 
list a catalog's entries arei 


//LISTCAT 
//STEP1 
//STEPCAT 
//QUTDD 
// 

// 

//SYSPRINT DD 
//SYSIN 


JOB 

EXEC PGM=IDCAMS 
DD DSN=YOURCAT,DISP=SHR 

DD DSN=LISTCAT.OUTPUT,UNIT=TAPE, 

V0L=SER=TAPE1Q,LABEL=(1,NL),DISP=(NEW,KEEP), 
DCB=(RECFM=VBA,LRECL=125,BLKSIZE=629) 

SYSOUT=A 
DD X 

LISTCAT - 

CATALOGCYOURCAT/PASSWORD) - 
OUTFILE(OUTDD) - 


The JOB statement contains user and accounting information 
required for your installation. 

The EXEC statement identifies the program to be executed, IDCAMS 
(that is, the access method services program). 

• STEPCAT DD, which allocates your catalog. The catalog can 
be allocated dynamically if the STEPCAT and JOBCAT are 
omitted. If the catalog is dynamically allocated, its 
volume must be mounted as permanently RESIDENT or RESERVED. 

• OUTDD, which specifies an alternate output file, so that the 
LISTCAT output can be written onto an auxiliary storage 
device. The LISTCAT command's OUTFILE parameter points to 
the OUTDD DD statement. Only the LISTCAT output is written 
to the alternate output device. JCL statements, system 
messages, and job statistics are written to the SYSPRINT 
output device. 

— DSN=LISTCAT.OUTPUT specifies the name for the magnetic 
tape file. 

UNIT=2400-3 and V0L=SER=TAPE10 specifies that the file 
is to be contained on magnetic tape volume TAPE10. 

- LABEL=(1,NL) specifies that this is the first file on a 
nonlabeled tape. You can also use a standard labeled 
tape by specifying LABEL=(1,SL). If subsequent job 
steps produce additional files of LISTCAT output on the 
same tape volume, you should increase the file number in 
each job step's LABEL subparameter (that is, 

LABEL=(2,NL) for the second job step, LABEL=(3,NL) for 
the third job step, and so on.) 

— DISP=(NEW,KEEP) specifies that this is a new tape file 
and is to be rewound when the job finishes. If a 
subsequent job step prints the tape, DISP=(NEW,PASS) 
should be specified. If your job step contains more 
than one LISTCAT command, DISP=(M0D,KEEP) or 
DISP=(MOD,PASS) can be used to concatenate all of the 
LISTCAT output in one sequential file. 

DCB=(RECFM=VBA,LRECL=125,BLKSIZE=629) specifies that the 
LISTCAT output records are variable-length, blocked 
5-to-l, and are preceded by an ANSI print control 
character. 
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• SYSPRINT DD, which is required for each access method 
services job step. It identifies the output queue, 
SYS0UT=A, on which all LISTCAT output and system output 
messages are printed (unless the OUTFILE parameter and its 
associated DD statement is specified—see OUTDD above). 

Note: If you want all output to be written to an auxiliary 

storage device, replace 1 OUTDD 1 with ’'SYSPRINT 1 in the OUTDD DD 
statement and omit the SYSPRINT DD SYS0UT=A statement. 

• SYSIN DD, which specifies, with an asterisk (X), that the 
statements that follow are the input data statements. A 
VX* terminates the input data statements. 

The LISTCAT command parameters shown above are common to the 
LISTCAT examples that follow. Other LISTCAT parameters are 
coded with each example and the output that results is 
illustrated. These two parameters are optional: 

• CATALOG, which identifies the catalog, YOURCAT, whose 
entries are to be listed. If the catalog is password 
protected, its read- or highei—level password, PASSNORD, is 
required. If the passwords and protection attributes of 
each entry are to be listed, the catalog f s master password 
is required. 

• OUTFILE, which points to the OUTDD DD statement. The OUTDD 
DD statement allocates an alternate output file for the 
LISTCAT output. 

If you want to print the LISTCAT output that is contained on an 
alternate output file, you can use the IEBGENER program. The 
following shows the JCL required to print the alternate output 
file, LISTCAT.OUTPUT, that was allocated previously: 


//PRINTOUT 

JOB 

• • • 

//STEP1 

EXEC 

PGM=IEBGENER 

//SYSUT1 

DD 

DSN=LISTCAT.OUTPUT,UNIT=2400-3, 

// 

V0L = 

SER=TAPE10,LABEL=(1,NL),DISP=(OLD,KEEP), 

// 

DCB= 

CRECFM=VBA,LRECL=125,BLKSIZE=629) 

//SYSUT2 

DD 

SYS0UT=A 

//SYSPRINT 

DD 

SYS0UT=A 

//SYSIN 

DD 

DUMMY 


/x 
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LISTCAT AND ACCESS METHOD SERVICES OUTPUT MESSAGES 


When the LISTCAT job completes, access method services provides ; 
messages and diagnostic information. An analysis of any error ^ 

messages received can be found in Message Library? System 
Messages . When your LISTCAT job completes successfully, access 
method services provides messages that follow the entry listing 
(see Figure 10): 


LISTING FROM CATALOG -- MJKCAT 
THE NUMBER OF ENTRIES PROCESSED WAS; 


AIX-1 

ALIAS-2 

CLUSTER -5 

DATA-6 

GDG-1 

INDEX-3 

NONVSAM -2 

PAGESPACE -0 

PATH-2 

SPACE-0 

USERCATALOG -0 

TOTAL-22 


THE NUMBER OF PROTECTED ENTRIES SUPPRESSED WAS 0 
IDC0Q01I FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 0 
IDC0002I IDCAMS PROCESSING COMPLETE, MAXIMUM CONDITION CODE WAS 0 
Figure 10. Messages That Follow the Entry Listing 


The first line identifies the catalog that contains the listed 
entries. 

The next group of lines specify the number of each entry type 
and the total number of entries that were listed. This 
statistical information can help you determine the approximate 
size, in records, of your catalog. 

The next line specifies the number of entries that could not be 
listed because the appropriate password was not specified. 

The last two messages indicate that the LISTCAT command 
(FUNCTION) and the job step (IDCAMS) completed successfully. 
When LISTCAT is invoked from a TSO terminal, IDC0QQ1I is not 
printed. 
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LISTCAT OUTPUT LISTING 


When you specify LISTCAT with no parameters# the entryname and 
type of each entry are listed (see Figure 11 on page 280). The 
same listing would result if the NAMES parameter were specified. 

You can use this type of listing to list the name of each 
cataloged object and to determine the number of entries in the 
catalog. The total number of entries is an approximate size# in 
records# of your catalog. 
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/X 


LIST ENTRYNAMES OF THE CATALOG X/ 
LISTCAT - 

CATALOG (MJKCAT) 




w 


LISTING FROM CATALOG — MJKCAT 

AIX - MJK.ALT.INDEX1 

DATA - MJK.ALT.INDEX1.DATA 

INDEX - MJK.ALT.INDEX1.INDEX 

PATH - MJK.AIX1.PATH 

CLUSTER - MJK.CLUSTER1 

DATA - MJK.CLUSTER.DATA 

INDEX - MJK.CLUSTER1.INDEX 

GDG BASE-MJK.GDG1 

NONVSAM - MJK.GDG1.G0001V00 

ALIAS - MJK.GDG1.ALIAS 

NONVSAM - MJK.NONVSAM1 

CLUSTER - MJKCAT 

DATA - VSAM.CATALOG.BASE.DATA.RECORD 

INDEX - VSAM.CATALOG.BASE.INDEX.RECORD 

VOLUME - 333001 

LISTING FROM CATALOG — MJKCAT 


THE NUMBER OF ENTRIES PROCESSED WAS: 


AIX-1 

ALIAS-1 

CLUSTER -2 

DATA-3 

GDG-1 

INDEX-3 

NONVSAM -2 

PAGESPACE -0 

PATH-1 

SPACE-0 

USERCATALOG -0 

TOTAL-14 


THE NUMBER OF PROTECTED ENTRIES SUPPRESSED WAS 0 
IDC0001I FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 0 
IDC0002I IDCAMS PROCESSING COMPLETE. MAXIMUM CONDITION CODE WAS 0 
Figure 11. Example of LISTCAT Output When No Parameters Are Specified 
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LISTCAT VOLUME OUTPUT LISTING 



When the LISTCAT command is specified with the VOLUME parameter, 
the volume serial number and device type of each volume that 
contains part or all of the cataloged object are listed (see 
Figure 12). 


/» LIST VOLUMES FOR EACH ENTRY »/ 
LISTCAT - 

VOLUME - 

CATALOG CMJKCAT) 


LISTING FROM CATALOG — MJKCAT 


AIX - MJK.ALT.INDEX1 

HISTORY 

OWNER-IDENT-(HULL) CREATION.77.040 RCVY-VOl.333001 RCVY-CI.X'000010* 

RELEASE-2 EXPIRATION.00.000 RCVY-DEVT-X' 30502009' 

0ATA - MJK.ALT.IN0EX1.0ATA 

HISTORY 

OWNER-IDENT-(NULL) CREATION-77.040 RCVY-VOL. 333001 RCVY-CI.X* 000011* 

RELEASE-2 EXPIRATION-00.000 RCVY-DEVT-X* 30502009* 

VOLUMES 

VOLSER-333001 DEVTYPE.X * 30502009 * 

INDEX - MJK.ALT.INDEX1.INDEX 

HISTORY 

OWNER-IDENT-(NULL) CREATION-77.040 RCVY-VOL-333001 RCVY-CI-X* 000012* 

RELEASE- 2 EXPIRATION-00.000 RCVY-DEVT-X* 30502009' 

VOLUMES 

VOLSER—.—333001 DEVTYPE.X'30502009' 

PATH - MJK.AIX1.PATH 

HISTORY 

OWNER-IOENT.—(NULL) CREATION.77.040 RCVY-VOL-333001 RCVY-CI-X* 000014' 

RELEASE- 2 EXPIRATION-00.000 RCVY-DEVT-X'30502009* 

CLUSTER . MJK.CLUSTER! 

HISTORY 

OWNER-IDENT-OWNCLUST CREATION-77.040 RCVY-VOL.—333001 RCVY-CI-X'OOOOOE* 

RELEASE- -2 EXPIRATION.—77.140 RCVY-DEVT-X' 30502009' 

OATA . MJK.CLUSTER.DATA 

HISTORY 

OWNER-IDENT-(NULL) CREATION..77.040 RCVY-VOL-333001 RCVY-CI-X' 00000D' 

RELEASE.-.2 EXPIRATION.00.000 RCVY-DEVT-X' 30502009 • 

VOLUMES 

VOLSER.333001 DEVTYPE.X* 30502009' 

INOEX - MJK.CLUSTER1.INDEX 

HISTORY 

OWNER-IDENT-(NULL) CREATION-77.040 RCVY-VOL.—333001 RCVY-CI-.X'OOOOOF* 

RE LEASE.2 EXPIRATION-00.000 RCVY-DEVT-X' 30502009' 

VOLUMES 

VOLSER.333001 DEVTYPE.X'30502009' 

GOG BASE.MJK.GDG1 

HISTORY 

OWNER-IOENT.OWNGOG CREATION-77.040 RCVY-VOL—.333001 RCVY-CI.X'000015* 

RELEASE.2 EXPIRATION.99.365 RCVY-DEVT-X'30502009' 


NONVSAM - MJK.GDG1.G0001V00 

HISTORY 


OWNER-IDENT- 

RELEASE- 

VOLUMES 

VOLSER- 

VOLSER. 

— (NULL) 
.2 

—333001 

— 333002 

CREATION— 

EXPIRATION- 

DEVTYPE— 
DEVTYPE- 

-77.040 

- 00.000 

—X'30502009' 

—X*30502009' 

RCVY-VOL-333001 

RCVY-DEVT-X ’ 30502009 • 

RCVY-CI- 

-X’000016 

Figure 12 (Part 

1 of 2). 

Example 

of LISTCAT 

VOLUME Output 




Appendix A. Interpreting LISTCAT Output Listings 281 

















































































NONVSAM - MJK.NONVSAM1 

HISTORY 

OWNER-ID ENT-(NULL) CREATION.77.040 RCVY-VOL.333001 RCVY-CI X* 000010* 

RELEASE-2 EXPIRATION-00.000 RCVY-OEVT-X* 30502009' 

VOLUMES 

VOLSER. 333001 DEVTYPE-X'30502009' 

CLUSTER - MJKCAT 

HISTORY 

OHNER-IDENT.(NULL) CREATION-77.040 

RELEASE-2 EXPIRATION-99.999 

DATA - VSAM.CATALOG.BASE.DATA.RECORD 

HISTORY 

OWNER-ID ENT.(NULL) CREATION.00.000 

RELEASE-2 EXPIRATION-00.000 

VOLUMES 

VOLSER.333001 OEVTYPE.X' 30502009* 

INDEX . VSAM.CATALOG.BASE.INDEX.RECORD 

HISTORY 

OWNER-IDENT.(NULL) CREATION.00.000 

RELEASE- 2 EXPIRATION-00.000 

VOLUMES 

VOLSER.333001 DEVTYPE.X'30502009' 

VOLUME .- 333001 

HISTORY 

RE LEASE- 2 RCVY-VOL-333001 RCVY-DEVT-X' 30502009' RCVY-CI-X' 000009' 

VOLUMES 

VOLSER.333001 DEVTYPE-X'30502009' 


LISTING FROM CATALOG — MJKCAT 


THE NUMBER OF ENTRIES PROCESSED WAS: 


AIX.1 

ALIAS. 0 

CLUSTER .2 

DATA.--3 

GDG.-.1 

INDEX —. 3 

NONVSAM - 2 

PAGESPACE--0 

PATH.—-1 

SPACE.-.1 

USERCATALOG..0 

TOTAL.14 


THE NUMBER OF PROTECTED ENTRIES SUPPRESSED WAS 0 
IDC0001I FUNCTION COMPLETED* HIGHEST CONDITION CODE WAS 0 
IDC0002I IDCAMS PROCESSING COMPLETE. MAXIMUM CONDITION CODE WAS 0 


Figure 12 (Part 2 of 2). Example of LISTCAT VOLUME Output 
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LISTCAT SPACE ALL OUTPUT LISTING 


When the LISTCAT command is specified with the SPACE and ALL 
parameters, all the information for each volume entry in the 
catalog is listed (see Figure 13). You can use this type of 
listing to determine how space on each cataloged volume is 
allocated to VSAM data spaces. You may have to list the 
volume's table of contents (VTOC) to determine how all of the 
volume's space is allocated. 


/* LIST VOLUME INFORMATION FOR THE VOLUMES - 
CONTROLLED BY THE CATALOG «/ 

LISTCAT - 
SPACE - 
ALL - 

CATALOG!MJKCAT) 


LISTING FROM CATALOG — MJKCAT 


VOLUME - 333001 

HISTORY 

RELEASE-2 

CHARACTERISTICS 

BYTES/TRK-13165 

TRKS/CYL-19 

CYLS/VOL-411 

OATASPACE 

OATASETS.5 

EXTENTS- 1 

SEC-ALLOC.40 

TYPE- —TRACK 

EXTENT-DESCRIPTOR: 

TRACKS-TOTAL.160 

TRACKS-USED..89 

DATASET-DIRECTORY: 

DSN——MJKCAT 


DSN-MJK.CLUSTER.DATA 

DSN-MJK.CLUSTER1.INDEX 

DSN-MJK.ALT.INDEX1.DATA 

DSN-MJK.ALT.INDEX1.INDEX 


RCVY-VOL-333001 

DEVTYPE.X' 30502009* 

VOLUME-TIMESTAMP: 

X'8A51B6A76850E000' 

FORMAT-l-DSCB: 

CCHHR-X* 0000000103* 

TIMESTAMP 

X'8A51B61D97B04000' 
BEG-CCHH-X' 00000002' 


RCVY-DEVT-X»30502009 * 


MAX-PHYREC-SZ-13030 

MAX-EXT/ALLOC-5 


ATTRIBUTES: 

SUBALLOC 

EXPLICIT 

USERCAT 


SPACE-MAP-5947 


ATTRIBUTES-(NULL) 

ATTRIBUTES-(NULL) 

ATTRIBUTES.(NULL) 

ATTRIBUTES.—(NULL) 

ATTRIBUTES-(NULL) 


RCVY-CI-X* 000009* 

DATASETS-ON-VOL-5 

DATASPCS-QN-VOL—.1 


EXTENTS-3 

EXTENTS-1 

EXTENTS-1 

EXTENTS-1 

EXTENTS-1 


LISTING FROM CATALOG — MJKCAT 


THE NUMBER OF ENTRIES PROCESSED WAS: 


AIX. 0 

ALIAS —.-.0 

CLUSTER. 0 

DATA —- 0 

GDG.0 

INDEX. 0 

NONVSAM.-.0 

PAGESPACE .0 

PATH.—.0 

SPACE.1 

USERCATALOG.0 

TOTAL.1 


THE NUMBER OF PROTECTED ENTRIES SUPPRESSED WAS 0 
IDC0001I FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 0 
IDC0002I IDCAMS PROCESSING COMPLETE. MAXIMUM CONDITION CODE WAS 0 

Figure 13. Example of LISTCAT SPACE ALL Output 
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LISTCAT ALL OUTPUT LISTING 


When you specify the LISTCAT command and include the ALL 
parameter^ all the information for each catalog entry is listed. 
The example in Figure 14 on page 285 illustrates the LISTCAT 
output for each type of catalog entry. You can use this type of 
listing to obtain all cataloged information (except password and 
security information) about each entry that is listed. When you 
want to list an entry f s passwords, you must provide the 
catalog v s master password (which results in listing the 
passwords of each password-protected entry) or each entry*s 
master password. 

Note: When ENTRIES is specified, you specify only those 
entrynames that identify catalog entries that are not volume 
entries. If a volume serial number is specified with the 
ENTRIES parameter, entrynames of other entry types cannot also 
be specified. However, if the ENTRIES parameter is not 
specified and if entry types are not specified (that is, 

CLUSTER, SPACE, DATA, and so forth), all entries in the catalog, 
including volume entries, are listed. 
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/* LIST ALL CATALOGEO INFORMATION FOR EACH ENTRY */ 
LISTCAT - 
ALL - 

CATALOG (MJKCAT) 


LISTING FROM CATALOG — MJKCAT 


AIX - MJK.ALT.INOEX1 

HISTORY 

OMNER-IDENT-(NULL) CREATION.77.040 

RELEASE-2 EXPIRATION..00.000 

PROTECTION-PSHO-(NULL) RACF..(NO) 

ASSOCIATIONS 

OATA-MJK.ALT.INDEX1.DATA 

INDEX-MJK.ALT.INOEX1.INDEX 

CLUSTER—MJK .CLUSTER I 

PATH-MJK.AIXi .PATH 

ATTRIBUTES 

UPGRADE 


RCVY-VOL-333001 RCVY-CI-X '000010' 

RCVY-DEVT-X 1 30502009' 



OATA - MJK.ALT.INOEX1.OATA 

HISTORY 

OMNER-IDENT-(NULL) 

RELEASE.2 

PROTECTION-PSWD-(NULL) 

ASSOCIATIONS 

AIX-MJK.ALT. INOEX1 

ATTRIBUTES 

KEYLEN. 5 

RKP.5 

AXRKP—------------_45 

SHROPTNS(1,3) RECOVERY 
UNORDEPED NOREUSE 

STATISTICS 

REC-TOTAL.4 

REC-DELETED.0 

REC-INSERTED. 0 

REC-UPOATEO.0 

REC-RETRIEVED.0 

ALLOCATION 

SPACE-TYPE.TRACK 

SPACE-PRI.6 

SPACE-SEC.6 

VOLUME 

VOLSER.-.333001 

OEVTYPE.X'30502009' 

VOLFLAG.PRIME 

EXTENTS: 

LOM-CCHH-X' 00040008' 

HIGH-CCHH-X* 00040000‘ 


CREATION-77.040 

EXPIRATION.00.000 

RACF- (NO) 


AVGLRECL-4086 

MAXLRECL—.32600 

SUBALLOC NOERASE 

SPANNED NONUNIQKEY 


SPLITS-CI.-.0 

SPLITS-CA-0 

FREESPACE-ZCI..0 

FREESPACE-XCA.—0 

FREESPC-BYTES-69632 


HI-ALLOC-RBA.73728 

HI-USED-RBA.73728 

PHYREC-SIZE-4096 

PHYRECS/TRK. 3 

TRACKS/CA-6 

LOW-RBA-0 

HIGH-RBA.73727 


RCVY-VOL-333001 RCVY-CI-X'000011' 

RCVY-OEVT-X'30502009* 


BUFSPACE-8704 CISIZE-4096 

EXCPEXIT-(NULL) CI/CA-18 

INDEXED NOMRITECHK NOIMBED NOREPLICAT 


EXCPS--7 

EXTENTS-1 

SYSTEM-TIMESTAMP: 

X 1 8A51B6C0C87CF000 * 


HI-ALLOC-RBA-73728 

HI-USED-RBA-73728 

TRACKS-6 


EXTENT-NUMBER-1 

EXTENT-TYPE-X'OO* 


Figure 14 (Part 1 of 7). Example of LISTCAT ALL Output 
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MJK.ALT.INDEX!.INDEX 


INDEX — 

UTCTODY 

OWNER-IOENT-(NULL) 

RELEASE-.2 

PROTECT ION-PSMO-(NULL) 

ASSOCIATIONS 

AIX.MJK. ALT. INDEX1 

ATTRIBUTES 

KEYLEN--- 5 

RKP.5 

SHROPTNSCI»3) RECOVERY 
NOREUSE 
STATISTICS 

REC-TOTAL.1 

REC-DELETED.0 

REC-INSERTEO-0 

REC-UPDATEO.0 

REC-RETRIEVED-0 

ALLOCATION 

SPACE-TYPE-TRACK 

SPACE-PRI.1 

SPACE-SEC-1 

VOLUME 

VOLSER- 333001 

OEVTYPE-—-X ' 30502009 * 

VOLF LAG-PRIME 

EXTENTS: 

LOM-CCHH-X'0004000E' 

HIGN-CCHH-X *0004000E• 


CREATION-77.040 

EXPIRATION--00.000 

RACF-(NO) 


AVGLRECL-0 

MAXLRECL-505 

SUBALLOC NOERASE 

SPLITS-CI-—0 

SPLITS-CA-0 

FREESPACE-XCI-0 

FREESPACE-XCA-0 

FREESPC-BYTES-9726 

HI-ALLOC-RBA-10240 

HI-USED-RBA-512 

PHYREC-SIZE-512 

PHYRECS/TRK-20 

TRACKS/CA-1 

LOU-RBA-0 

MIGH-RBA..10239 


PATH - MJK.AIX1.PATH 

HISTORY 

OWNER-IOENT--(NULL) CREATION- 

RELEASE.. 2 EXPIRATION 

PROTECTION-PSWO-(NULL) RACF- 

ASSOCIATIONS 

AIX-MJK. ALT. INDEX1 

DATA-MJK.ALT.INDEX1.DATA 

INOEX-MJK.ALT.INDEX1.INDEX 

DATA-MJK .CLUSTER.DATA 

INDEX——MJK.CLUSTER1 .INDEX 
ATTRIBUTES 
UPDATE 

CLUSTER - MJK.CLUSTER1 

HISTORY 

OWNER-IOENT-OWNCLUST CREATION-77.040 

RELEASE.2 EXPIRATION-77.140 

PROTECTION 

MASTERPW-MASTCL UPDATEPW-UPDCL 

CONTROLPW.CNTLCL READPW..READCL 

USAR..(NONE) 

ASSOCIATIONS 

OATA——MJK. CLUSTER 1 .DATA 
INOEX——MJK. CLUSTER 1. INOEX 
AIX-MJK. ALT. INDEX! 


•77.040 

00.000 

—(NO) 


RCVY-VOL-333001 RCVY-CI-X'000012' 

RCVY-DEVT-X*30502009• 


/"A 

w 


BUFSPACE-0 

EXCPEXIT- (NULL) 

NOWRITECHK NOIMBED 


CISIZE-512 

CI/CA-20 

NOREPLICAT UNORDEREO 


EXCPS-3 

EXTENTS-1 


SYSTEM-TIMESTAMP: 

X 1 6A51B6C0C87CF000 * 


INDEX: 

LEVELS-1 

ENTRIES/SECT-4 

SEQ-SET-RBA-0 

HI-LEVEL-RBA-0 


HI-ALLOC-RBA-10240 

HI-USEO-RBA-512 

TRACKS-1 

RCVY-VOL-333001 


RCVY-DEVT-X 1 30502009 * 


EXTENT-NUMBER-1 

EXTENT-TYPE-X'OO' 


RCVY-CI-X'000014* 


RCVY-VOL-333001 RCVY-CI-X* 00000E * 

RCVY-DEVT-X * 30502009• 


CODE-CODEC L RACF-(NO) 

ATTEMPTS-3 USVR-(NULL) 


Figure 14 (Part 2 of 7). 


Example of LISTCAT ALL Output 


ff' 

V. 
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MJK.CLUSTER.DATA 


OATA- 

HISTORY 

OWNER-ID ENT.(NULL) 

RELEASE.2 

PROTECTION-PSWO-(NULL) 

ASSOCIATIONS 

CLUSTER—MJK. C LUSTER 1 
ATTRIBUTES 

KEYLEN- -5 

RKP..5 

SHROPTNSC1,3) RECOVERY 

UNORDERED NOREUSE 

STATISTICS 

REC-TOTAL..20 

REC-DELETEO..0 

REC-INSERTED.0 

REC-UPDATED—.0 

REC-RETRIEVED-20 

ALLOCATION 

SPACE-TYPE.TRACK 

SPACE-PRI.2 

SPACE-SEC..2 

VOLUME 

VOLSER-.333001 

DEVTYPE-X'30502009' 

VOLFLAG-PRIME 

EXTENTS: 

LOW-CCHH-X' 00040005' 

HIGH-CCHH-X'00040006' 

INDEX - MJK.CLUSTER1.INDEX 

HISTORY 

OWNER-ID ENT.(NULL) 

RELEASE.-2 

PROTECTION-PSWD-(NULL) 

ASSOCIATIONS 

CLUSTER—MJK. C LUSTER 1 
ATTRIBUTES 

KEYLEN.-.5 

RKP- 5 

SHROPTNS(1,3) RECOVERY 

NOREUSE 
STATISTICS 

REC-TOTAL..1 

REC-DELETED.0 

REC-INSERTED--0 

REC-UPDATED-.—0 

REC-RETRIEVED-0 

ALLOCATION 

SPACE-TYPE-TRACK 

SPACE-PRI.1 

SPACE-SEC—.1 

VOLUME 

VOLSER-333001 

DEVTYPE.X’30502009' 

VOLFLAG—.PRIME 

EXTENTS: 

LOW-CCHH-X'00040007' 

HIGH-CCHH-X'00040007' 

GDG BASE.MJK.GDG1 

HISTORY 

OWNER-IDENT-OWNGDG 

RELEASE.2 

ATTRIBUTES 

LIMIT.250 

ASSOCIATIONS 

NONVSAM—MJK.GDG1 .GOOOIVOO 


CREATION-77.040 

EXPIRATION-00.000 

RACF-(NO) 

AVGLRECL- 80 

MAXLRECL. 100 

SUBALLOC NOERASE 

NONSPANNED 

SPLITS-CI-0 

SPLITS-CA.0 

FREESPACE-XCI-15 

FREESPACE-XCA.20 

FREESPC-BYTES-12288 

HI-ALLOC-RBA-24576 

HI-USED-RBA-24576 

PHYREC-SIZE-4096 

PHYRECS/TRK. 3 

TRACKS/CA---2 

LOW-RBA.-0 

HIGH-RBA-24575 

CREATION-77.040 

EXPIRATION-00.000 

RACF-(NO) 

AVGLRECL-0 

MAXLRECL..505 

SUBALLOC NOERASE 

SPLITS-CI-0 

SPLITS-CA- 0 

FREESPACE-XCI.-0 

FREESPACE-XCA..0 

FREESPC-BYTES-9728 

HI-ALLOC-RBA-10240 

HI-USED-RBA.512 

PHYREC-SIZE-512 

PHYRECS/TRK. 20 

TRACKS/CA-1 

LOW-RBA- 0 

HIGH-RBA.10239 

CREATION-77.040 

EXPIRATION-99.365 


SCRATCH 


EMPTY 


RCVY-VOL-333001 RCVY-CI- 

RCVY-DEVT-X' 30502009' 


-X'OOOOOD’ 


BUFSPACE-25088 CISIZE-- 

EXCPEXIT—-EXITCLUS CI/CA- 

INDEXED NOWRITECHK NOIMBED 

EXCPS-4 

EXTENTS-1 

SYSTEM-TIMESTAMP: 

X'6A51B6ACD5B92000' 


-12288 

-2 

NOREPLICAT 


EXTENT-NUMBER- 

EXTENT-TYPE— 


HI-ALLOC-RBA-24576 

HI-USED-RBA-24576 

TRACKS-2 


RCVY-VOL-333001 RCVY-CI- 

RCVY-DEVT-X * 30502009' 


-X'OO' 


-X'OOOOOF' 


CISIZE- 

CI/CA- 

NOREPLICAT 


BUFSPACE-0 

EXCPEXIT-EXITCLUS 

NOWRITECHK NOIMBED 

EXCPS-4 

EXTENTS-1 

SYSTEM-TIMESTAMP: 

X'8A51B6ACD5B92000’ 


HI-ALLOC-RBA-10240 

HI-USED-RBA-512 

TRACKS-1 


RCVY-VOL-333001 RCVY-CI- 

RCVY-DEVT-X'30502009' 


-512. 

.20 

UNORDERED 


INDEX: 

LEVELS-1 

ENTRIES/SECT-1 

SEQ-SET-RBA-0 

HI-LEVEL-RBA-0 


EXTENT-NUMBER- 

EXTENT-TYPE— 


-1 


-X'OO' 


-X'000015' 


Figure 14 (Part 3 of 7). Example of LISTCAT ALL Output 
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NONVSAM - MJK.GDG1.G0001V00 

HISTORY 


OWNER-IDENT- 

-(NULL) 

CREATION- — 

.77.040 

RCVY-VOL-333001 

RCVY-DEVT-X * 30502009 * 

RELEASE- 

VOLUMES 


ncuTvnc 


VOLSER- 

VOLSER.. 

----333001 
-333002 

UtVTYPE—- 

DEVTYPE- 

"•A jJPUcvUt 

—X'30502009* 

rOtVrl v 

FSEQN.0 


ASSOCIATIONS 

GOG.MJK.GDG1 

ALIAS-MJK.GDGI.ALIAS 


RCVY-CI-X' 000016' 


ALIAS . MJK.G0G1.ALIAS 

HISTORY 

RELEASE..2 RCVY-VOL.333001 

ASSOCIATIONS 

NONVSAM—MJK.GOG1.GOOOIVOO 


RCVY-OEVT-X’30502009’ 


RCVY-CI-X’000017* 


NONVSAM . MJK.NONVSAM1 

HISTORY 


OWNER-IDENT- 

-(NULL) 

CREATION- 

-77.040 

RELEASE. 

.2 

EXPIRATION- 

- 00.000 

VOLUMES 




VOLSER.. 

-333001 

DEVTYPE- 

-X'30502009* 

ASSOCIATIONS. 

-(NULL) 




RCVY-VOL-333001 RCVY-CI X* 000018* 

RCVY-OEVT-X*30502009* 

FSEQN- 0 


CLUSTER . MJKCAT 

HISTORY 

OUNER-IDENT.(NULL) CREATION-77.040 

RELEASE-.2 EXPIRATION.99.999 

PROTECT ION-PSWD-(NULL) RACF---(NO> 

ASSOCIATIONS 

DATA-VSAM.CATALOG.BASE.DATA.RECORD 

INDEX-VSAM.CATALOG.BASE.INDEX.RECORD 


Figure 14 (Part 4 of 7). Example of LISTCAT ALL Output 
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DATA - VSAM.CATALOG.BASE.DATA.RECORD 

HISTORY 

OWNER-ID ENT.(NULL) 

RELEASE. 2 

PROTECTION-PSWD-(NULL ) 

ASSOCIATIONS 
CLUSTER— MJKCAT 
ATTRIBUTES 

KEYLEN..44 

RKP..0 

SHROPTNS(3>3) RECOVERY 
UNOROERED NOREUSE 

STATISTICS 

REC-TOTAL.15 

REC-DELETED.0 

REC-INSERTED.0 

REC-UPDATED.0 

REC-RETRIEVED.0 

ALLOCATION 

SPACE-TYPE.TRACK 

SPACE-PRI.57 

SPACE-SEC-IS 

VOLUME 

VOLSER.333001 

DEVTYPE.X 1 30502009' 

VOLF LAG.PRIME 

LOW-KEY.-00 

HIGH-KEY.3F 

HI-KEY-RBA—.6144 

EXTENTS: 

LOW-CCHH.X'00000002' 

HIGH-CCHH-X'00020011* 

VOLUME 

VOLSER.333001 

DEVTYPE.X'30502009' 

VOLF LAG.PRIME 

LOW-KEY.40 

HIGH-KEY.FF 

HI-KEY-RBA.368640 

EXTENTS: 

LOW-CCHH.X* 00030002* 

HIGH-CCHH-X'00030004' 


CREATION. 00.000 

EXPIRATION-00.000 

RACF-(NO) 


AVGLRECL.505 

MAXLRECL-505 

SUBALLOC NOERASE 

NONSPANNED BIND 

SPLITS-CI-0 

SPLITS-CA.0 

FREESPACE-XCI.0 

FREESPACE->:CA~.0 

FREESPC-BYTES.381952 


HI-ALLOC-RBA.389120 

HI-USED-RBA.389120 

PHYREC-SI2E.512 

PHYRECS/TRK- 20 

TRACKS/CA-.3 


LOW-RBA-- 0 

HIGH-RBA-368639 

PHYREC-SIZE-512 

PHYRECS/TRK.20 

TRACKS/CA.3 


LOW-RBA— 

HIGH-RBA- 


-368640 

-389119 


BUFSPACE- 

EXCPEXIT- 

INDEXED 

RECVABLE 

.3072 

-(NULL) 

NOWRITECHK 

CALPO” 

EXTENTS. 

.2 

SYSTEM-TIMESTAMP: 

X'6A51B6244C1B1000' 

HI-ALLOC-RBA- 

-368640 

HI-USED-RBA— 

-20480 

TRACKS.— 

-54 

HI-ALLOC-RBA- 

-389120 

HI-USED-RBA— 

.389120 

TRACKS- 

-3 


CISIZE.512 

CI/CA- 40 

IMBED NOREPLICAT 


EXTENT-NUMBER-1 

EXTENT-TYPE-X'OO* 


EXTENT-NUMBER-1 

EXTENT-TYPE-X'OO' 


Figure 14 (Part 5 of 7). Example of LISTCAT ALL Output 
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INDEX - VSAM.CATALOG.BASE.INDEX.RECORD 


HISTORY 

OWNER-10 ENT.(NULL) CREATION.. 

RELEASE.-.2 EXPIRATION- 

PROTECTION-PSWD-(NULL) RACF.. 

ASSOCIATIONS 
CLUSTER—MJKCAT 
ATTRIBUTES 

KEYLEN. 44 AVGLRECL- 

RKP.0 NAXLRCCL - 

SHR0PTNS(3t3) RECOVERY SUBALLOC 

NOREUSE BIND 

STATISTICS 

REC-TOTAL.3 SPLITS-CI- 

REC-OELETEO.0 SPLITS-CA- 

REC-INSERTEO.0 FREESPACE-XCI 

REC-UPDATED- 0 FREESPACE-XCA 

REC-RETRIEVED--0 FREESPC-6YTES 

ALLOCATION 

SPACE-TYPE.TRACK 

SPACE-PRI.3 HI-ALLOC-RBA- 

SPACE-SEC.3 HI-USED-RBA-- 

VOLUME 

VOLSER.333001 PHYREC-SIZE— 

OEVTYPE.X'30502009* PHYRECS/TRK— 

VOLF LAG.PRIME TRACKS/CA- 

EXTENTS; 

LOW-CCHH.X * 00020012 * LOW-RBA. 

HIGH-CCHH-X 1 00030001' HIGH-RBA- 

VOLUME 

VOLSER.333001 PHYPEC-SIZE — 

OEVTYPE.X*30502009' FHYPECS/TRK-- 

VOLFLAG. PRIME TRACKS/CA- 

LOW-KEY-—. 00 

HIGH-KEY-—.3F 

EXTENTS: 

LOW-CCHH.X'00000002' LCW-RBA- 

HIGH-CCHH-X'00020011' HIGH-RBA- 

VOLUME 

VOLSER.—333001 PHYREC-SIZE — 

OEVTYPE-X' 30502009 • PHYRECS/TRK— 

VOLFLAG.PRIME TRACKS/CA- 

LQW-KEY.40 

HIGH-KEY.-.FF 

EXTENTS: 

LOW-CCHH-X'00030002' LOW-RBA. 


HIGH-CCHH-X'00030004' HIGH-RBA 


00.000 
00.000 
— (NO) 


-0 

-505 

NOERASE 


——0 

-0 

-0 

——0 
38912 


40448 

40448 

—512 
- — 20 
-1 

——0 
30719 

—512 

—20 

——3 


30720 

39935 

—512 

- 20 

- 3 


39936 

Y0447 


BUF SPACE-0 

EXCPEXIT-(NULL) 

NGi'Rl'TECHK IM3E0 


EXCPS.-..13 

EXTENTS.3 


SYSTEM-TIMESTAMP: 

X'8A51B6244C1B1000' 


HI-ALLOC-RBA-30720 

HI-USED-RBA—.512 


TRACKS- 


3 


HI-ALLOC-RBA—.39936 

HI-USED-RBA-31232 


TRACKS--54 


HI-ALLOC-RBA-40448 

HI-USED-RBA-40448 


TRACKS 


3 


CISIZE- 

CI/CA- 

NCREPLICAT 


-512 

-20 

UNORDERED 


INDEX: 

LEVELS-2 

ENTRIES/SECT..7 

SEQ-SET-RBA-30720 

HI-LEVEL-RBA-0 


EXTENT-NUMBER-1 

EXTENT-TYPE-X'OO' 


EXTENT-NUMBER-1 

EXTENT-TYPE-X'80‘ 


\ 

EXTENT-NUMBER-1 

EXTENT-TYPE-X'80* 


Figure 14 (Part 6 of 7). Example of LISTCAT ALL Output 
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333001 


VOLUME- 

HISTORT 

RELEASE.2 

CHARACTERISTICS 

BYTES/TRK—.13165 

TRKS/CYL. 19 

CYLS/VOL—.411 

DATASPACE 

DATASETS.5 

EXTENTS.1 

SEC-ALLOC.40 

TYPE-TRACK 

EXTENT-DESCRIPTOR: 

TRACKS-TOTAL..160 

TRACKS ~USEO...09 


DATASET-DIRECTORY: 
DSN——MJKCAT 


RCVY-VOL..333001 

DEVTYPE-X* 3C502009* 

VOLUME-TIMESTAMP: 

X'8A51B6A76850E000 1 

FORMAT-1-DSCB: 

CCHHR-X' 0000000103' 

TIMESTAMP 

X'8A51B61D97B04000' 
BEG-CCHH.X’00000002 1 


DSN-MJK.CLUSTER.DATA 

OSN-MJK.CLU5TER1.INDEX 

DSN-MJK.ALT.INDEX1.OATA 

DSN-MJK.ALT.INOEX1.INDEX 


RCVY-DEVT—-X’ 30502009' 

MAX-PHYREC-SZ-13030 

MAX-EXT/ALLOC--5 


ATTRIBUTES: 

SUBALLOC 

EXPLICIT 

USERCAT 

SPACE-MAP-5947 


ATTRIBUTES-(NULL) 

ATTRIBUTES-(NULL) 

ATTRIBUTES.(NULL) 

ATTRIBUTES.(NULL) 

ATTRIBUTES-(NULL) 


RCVY-CI-X'OOCCOr 

DATASETS-ON-VOL-5 

DATASPCS-GN-VOL.L 


EXTENTS-3 

EXTENTS- 1 

EXTENTS.I 

EXTENTS-1 

EXTENTS. 1 


LISTING FROM CATALOG — MJKCAT 


THE NUMBER OF ENTRIES PPOCESSED WAS: 


AIX.1 

ALIAS. 1 

CLUSTER -.--2 

DATA.---.3 

GOG. 1 

INDEX. 3 

NONVSAM -2 

PAGESPACE . 0 

PATH —.1 

SPACE.-.-.1 

USERCATALOG . 0 

TOTAL.15 


THE NUMBER OF PROTECTED ENTRIES SUPPRESSED WAS 0 
I0C0001I FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 0 
I0C0002I IOCAMS PROCESSING COMPLETE. MAXIMUM CONDITION CODE WAS 0 

Figure 14 (Part 7 of 7). Example of LISTCAT ALL Output 
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LISTCAT ALLOCATION OUTPUT LISTING 


/( N 

When you specify the LISTCAT command and include the ALLOCATION ( 
parameter^ each cataloged object with space allocated to it from 
a VSAM data space is listed (see Figure 15). All information 
about the object's space is listed/ but none of the object's 
other cataloged information is listed. The entry types that can 
be specified when the ALLOCATION parameter is specified are 
limited to DATA and INDEX. 


/* LIST SPACE ALLOCATION INFORMATION #/ 

LISTCAT - 

ALLOCATION - 
CATALOG(NJKCAT) 


AIX-MJK.ALT.INDEX1 

HISTORY 

OWNER-ID ENT-(NULL) 

RELEASE.2 


CREATION-77.040 RCVY-VOL-333001 RCVY-CI-X* 000010* 

EXPIRATION-00.000 RCVY-DEVT-X * 30502009' 


OATA-MJK.ALT. INOEX1 . 1 

HISTORY 

OWNER-IOENT-(NULL) 

RELEASE-2 

ALLOCATION 

SPACE-TYPE-TRACK 

SPACE-PRI.6 

SPACE-SEC.6 

VOLUME 

VOLSER-333001 

OEVTYPE-X'30502009* 

VOLFLAG.PRIME 

EXTENTS: 

LOW-CCHH-X * 00040008 * 

HIGH-CCHH-X * 0004000D* 


CREATION-77.040 

EXPIRATION-00.000 

HI-ALLOC-RBA-73728 

HI-USED-RBA-73728 

PHYREC-SIZE..4096 

PHYRECS/TRK-3 

TRACKS/CA-6 

LOW-RBA-0 

HIGH-RBA-73727 


RCVY-VOL.333001 

RCVY-DEVT-X*30502009* 


HI-ALLOC-RBA.73728 

HI-USED-RBA-73728 

TRACKS--6 


RCVY-CI-X* 000011* 


EXTENT-NUMBER-1 

EXTENT-TYPE-X*00* 


INDEX-MJK.ALT.INDEX1.: 

HISTORY 

OWNER-ID ENT-(NULL) 

RELEASE.2 

ALLOCATION 

SPACE-TYPE-TRACK 

SPACE-PRI. 1 

SPACE-SEC.1 

VOLUME 

VOLSER.333001 

OEVTYPE-X* 30502009* 

VOLFLAG.PRIME 

EXTENTS: 

LOW-CCHH-X* 0004000E' 

HIGH-CCHH-X * 0004000E' 


CREATION-77.040 

EXPIRATION.00.000 

HI-ALLOC-RBA.10240 

HI-USED-RBA-512 

PHYREC-SIZE.512 

PHYRECS/TRK- 20 

TRACKS/CA- 1 

LOW-RBA.0 

HIGH-RBA-10239 


RCVY-VOL..333001 

RCVY-OEVT-X*30502009* 


HI-ALLOC-RBA-10240 

HI-USE0-RBA-512 

TRACKS-1 


RCVY-CI- 


-X'000012* 


EXTENT-NUMBER-1 

EXTENT-TYPE-X*40* 


PATH - MJK.AIX1.PATH 

HISTORY 

OWNER-IOENT.(NULL) 

RELEASE.2 


CREATION-77.040 RCVY-VOL.—333001 RCVY-CI-X’000014* 

EXPIRATION-00.000 RCVY-DEVT-X* 30502009* 


CLUSTER . MJK.CLUSTER1 

HISTORY 

OWNER-IDENT-OWNCLUST 

RELEASE-.2 


CREATION.77.040 RCVY-VOL-333001 

EXPIRATION-77.040 RCVY-DEVT-X* 30502009* 


RCVY-CI-X'OOOOOE* 


Figure 15 (Part 1 of 3). Example of LISTCAT ALLOCATION Output 
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DATA 


MJK.CLUSTER.DATA 


HISTORY 

OWNER-ID ENT-C NULL) CREATION-77.040 

RELEASE-2 EXPIRATION-00.000 

ALLOCATION 

SPACE-TYPE-TRACK 

SPACE-PRI—.2 HI-ALLOC-RBA— 

SPACE-SEC-2 HI-USED-RBA- 

VOLUME 

VOLSER-333001 PHYREC-SIZE- 

DEVTYPE-X' 30502009* PH YRECS/TRK- 

VOLF LAG-PRIME TRACKS/CA- 

EXTENTS: 

LOW-CCHH-X • 00040005 * LOW-RBA-0 

HIGH-CCHH-X * 00040006 • HIGH-RBA-24575 


-24576 

-24576 


-6144 

-—2 


RCVY-VOL-333001 

RCVY-OEVT-X' 30502009 * 


HI-ALLOC-RBA-24576 

HI-USED-RBA-24576 

TRACKS-2 


RCVY-CI- 


-X 1 00000D' 


EXTENT-NUMBER- 

EXTENT-TYPE— 


-X'OO' 


INDEX - MJK.CLUSTER1.INDEX 

HISTORY 

OWNER-ID ENT-(NULL) 

RELEASE-2 

ALLOCATION 

SPACE-TYPE-TRACK 

SPACE-PRI-1 

SPACE-SEC-1 

VOLUME 

VOLSER-333001 

DEVTYPE-X* 30502009' 

VOLF LAG-PRIME 

EXTENTS: 

LOW-CCHH-X' 00040007 * 

HIGH-CCHH-X'00040007 * 


CREATION— 

EXPIRATION- 


HI-ALL0C-R8A- 

HI-USED-RBA— 


PHYREC-SIZE- 

PHYRECS/TRK- 

TRACKS/CA— 


LOW-RBA— 

HIGH-RBA- 


-77.040 

- 00.000 


-10240 
—512 


-512 
—20 
-1 


.0 

-10239 


RCVY-VOL-333001 

RCVY-DEVT-X' 30502009 * 


HI-ALLOC-RBA-10240 

HI-USEO-RBA-512 

TRACKS.. 1 


RCVY-CI- 


-X'OOOOOF' 


EXTENT-NUMBER- 

EXTENT-TYPE— 


-1 

-X'OO' 


CLUSTER - MJKCAT 

HISTORY 

OWNER-IDENT-(NULL) 

RELEASE--2 


CREATION- 

EXPIRATION- 


-77.040 

-99.999 


OATA - VSAM.CATALOG.BASE.DATA.RECORD 

HISTORY 

OWNER-IDENT-(NULL) CREATION- 

RELEASE-2 EXPIRATION- 

ALLOCATION 

SPACE-TYPE-TRACK 

SPACE-PRI.57 HI-ALLOC-RBA- 

SPACE-SEC..16 HI-USED-RBA— 

VOLUME 

VOLSER.333001 PHYREC-SIZE— 

OEVTYPE-X' 30502009' PH YRECS/TRK - - 

VOLF LAG.PRIME TRACKS/CA- 

LOW-KEY..00 

HIGH-KEY-3F 

HI-KEY-RBA-6144 

EXTENTS: 

LOW-CCHH-X'00000002' LOW-RBA- 

HIGH-CCHH-X’00020011' HIGH-RBA- 

VOLUME 

VOLSER-333001 PHYREC-SIZE— 

DEVTYPE-X * 30502009' PH YRECS/TRK— 

VOLF LAG-PRIME TRACKS/CA- 

LOW-KEY-—-40 

HIGH-KEY.FF 

HI-KEY-RBA-368640 

EXTENTS: 

LOW-CCHH-X' 00030002' LOW-RBA- 

HIGH-CCHH-X'00030004' HIGH-RBA- 


- 00.000 

- 00.000 


-389120 

-389120 


-512 

—20 

—3 


.0 

-368639 


-512 

—20 

—3 


-368640 

-389119 


HI-ALLOC-RBA-368640 

HI-USED-RBA-20480 


TRACKS-54 

HI-ALLOC-RBA-389120 

HI-USED-RBA-389120 


EXTENT-NUMBER- 

EXTENT-TYPE— 


-1 


-X'OO' 


EXTENT-NUMBER- 
EXTENT-TYPE— 


-X'OO' 


TRACKS- 


Figure 15 (Part 2 of 3). Example of LISTCAT ALLOCATION Output 
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VSAM.CATALOG.BASE.INDEX.RECORD 


INDEX - VSAM.CATALOG.BA! 

HISTORY 

OWNER-IDENT-(NULL) 

RELEASE.2 

ALLOCATION 

SPACE-TYPE-TRACK 

SPACE-PRI-—.3 

SPACE-SEC- 3 

VOLUME 

VOLSER-—-333001 

DEVTtPE.X'30502009' 

VOLFLAG..PRIME 

EXTENTS: 

LOM-CCHH.X* 00020012' 

HIGH-CCHH-X'00030001* 

VOLUME 

VOLSER.333001 

DEVTYPE.X'30502009' 

VOLFLAG-PRIME 

LOW-KEY.00 

HIGH-KEY.3F 

EXTENTS: 

LOM-CCHM.X'00000002' 

HIGH-CCHH-X'00020011' 

VOLUME 

VOLSER..333001 

OEVTYPE-X' 30502009' 

VOLFLAG.PRIME 

LOW-KEY.40 

HIGH-KEY.Fr 

EXTENTS: 

LOW-CCHH-X'00030002' 

HIGH-CCHH——X' 00030004 • 


CREATION--00.000 

EXPIRATION-00.000 


HI-ALLOC-RBA- 

HI-USED-RBA— 


PHYREC-SIZE- 

PHYRECS/TRK- 

TRACKS/CA— 


LOW-RBA--0 

HICH-RBA.—-30719 


PHYREC-SIZE- 

PHYRECS/TRK- 

TRACKS/CA— 


LOW-PBA-—30720 

HIGH-RBA.39935 


PHYREC-SIZE- 

PHYRECS/TRK- 

TRACKS/CA— 


LOW-RBA--39936 

HIGH-RBA.-40447 


HI-ALLOC-RBA- 
HI-U5ED-RBA-- 


EXTENT-NUMBER 
EXTENT-TYPE— 


HI-ALLCC-PBA- 

HI-USEO-PBA— 


EXTENT-NUMBER 

EXTENT-TYPE— 


HI-ALLOC-RBA- 

HI-USED-RBA— 


-4044B EXTENT-NUMBER 

-4C446 EXTENT-TYPE— 


LISTING FROM CATALOG — MJKCAT 


THE NUMBER OF ENTRIES PROCESSED WAS: 


AIX.1 

ALIAS.0 

CLUSTER -2 

DATA. 3 

GOG.0 

INDEX.3 

NCNVSAM.0 

PAGESPACE .0 

PATH.I 

SPACE-0 

USERCATALOG -.—0 

TOTAL.10 


THE NUMBER OF PROTECTED ENTRIES SUPPRESSED WAS 0 
IDC0001I FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 0 
IDC0002I IDCAMS PROCESSING COMPLETE. MAXIMUM CONDITION CODE WAS 0 

Figure 15 (Part 3 of 3). Example of LISTCAT ALLOCATION Output 
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LISTCAT HISTORY OUTPUT LISTING 


When you specify the LISTCAT command and include the HISTORY 
parameter, only the name, ownerid, creation date, and expiration 
date are listed for each entry that is selected (see Figure 16). 
Only these types of entries have HISTORY information: 
ALTERNATEINDEX, CLUSTER, DATA, INDEX, NONVSAM, and PATH. 


/# LIST HISTORY INFORMATION FOR EACH ENTRY «/ 

LISTCAT - 
HISTORY - 
CATALOGCMJKCAT) 


LISTING FROM CATALOG — MJKCAT 


AIX . MJK.ALT.IN0EX1 

HISTORY 

OWNER-IDENT.(NULL) 

RELEASE.2 


CREATION.77.040 

EXPIRATION-00.000 


RCVY-VOL..333001 

RCVY-0EVT-X'30502009* 


RCVY-CI-X'000010* 


OATA- 

HISTORY 

OWNER-IDENT 
RELEASE- 


MJK.ALT.INOEX1.DATA 
—(NULL) 


CREATION— 

EXPIRATION- 


-77.040 

- 00.000 


RCVY-VOL--333001 

RCVY-DEVT-X* 30502609' 


RCVY-CI-X* 00001I* 


INDEX . MJK.ALT.INOEX1.INDEX 

HISTORY 

OWNER-IDENT-(NULL) CREATION- 

RELEASE-2 EXPIRATION- 


-77.040 

- 00.000 


RCVY-VOL.333001 

RCVY-DEVT-X' 30502009* 


RCVY-CI.—X'000012' 


PATH - MJK.AIX1.PATH 

HISTORY 

OWNER-IDENT-(NULL) 

RELEASE.-.2 


CREATION— 

EXPIRATION- 


-77.040 

- 00.000 


RCVY-VOL.333001 

RCVY-DEVT-X'30502009* 


RCVY-CI-X* 000014* 


CLUSTER-MJK.CLUSTER 1 

HISTORY 

OWNER-IDENT-OWNCLUST 

RELEASE.-.2 


CREATION— 

EXPIRATION- 


-77.C40 

-77.140 


RCVY-VOL.— 333001 

RCVY-DEVT-X* 30502009' 


RCVY-CI-.X' OOOOOE * 


OATA . MJK.CLUSTER.DATA 

HISTORY 

OWNER-IDENT.(NULL) 

RELEASE--2 


CREATION— 

EXPIRATION- 


-77.040 

- 00.000 


RCVY-VOL.333001 

RCVY-DEVT-X*30502009* 


RCVY-CI-X'OOOOOD* 


INDEX -. MJK.CLUSTERi.INDEX 

HISTORY 

OWNER-IDENT.(NULL) 

RELEASE.2 


CPEATION.—77.040 

EXPIRATION.00.000 


RCVY-VOL..333001 

RCVY-DEVT-X* 305C2009* 


RCVY-CI-X' 00000F ' 


GDG BASE-MJK .GOG 1 

HISTORY 

OWNER-IOENT.OWNGDG 

RELEASE.2 


CREATION.75.223 

EXPIRATION.99.365 


RCVY-VOL--333001 

RCVY-DEVT-X* 30502009’ 


RCVY-CI.X'000015* 


NONVSAM - MJK.GDG1.GOOOIVOO 

HISTORY 

OWNER-IOENT-(HULL) 

RELEASE.2 


CREATION-77.040 

EXPIRATION.00.000 


RCVY-VOL-333001 

RCVY-DEVT-X*30502009' 


RCVY-CI-X* 000016* 


ALIAS . MJK.GDG1.ALIAS 

HISTORY 

RELEASE.2 


RCVY-VOL- 


-333001 


RCVY-DEVT-X*30502009* 


RCVY-CI.X* 000017* 


NONVSAM - MJK.NONVSAMl 

HISTORY 

OWNER-IOENT.(NULL) 

RELEASE.2 


CREATION— 

EXPIRATION- 


-77.040 

- 00.000 


RCVY-VOL.333001 

RCVY-DEVT-X’30502009* 


RCVY-CI.X'000010* 


Figure 16 (Part 1 of 2), Example of LISTCAT HISTORY Output 
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CLUSTER - MJKCAT 

HISTORY 

OWNER-IDENT-C NULL) CREATION-77.040 

RELEASE- 2 EXPIRATION-99.999 

DATA - VSAM.CATALOG.BASE.DATA.RECORD 

HISTORY 

OWNER-10 ENT-(NULL) CREATION..00.000 

RELEASE. 2 EXPIRATION.00.000 

INDEX .- VSAM.CATALOG.BASE.INDEX.RECORD 

HISTORY 

OWNER-IDENT.(NULL) CREATION.00.000 

RELEASE.2 EXPIRATION..00.000 

VOLUME . 333001 

HISTORY 

RELEASE.2 RCVY-VOL.—333001 RCVY-DEVT X* 30502009* RCVY-CI 


LISTING FROM CATALOG — MJKCAT 


THE NUMBER OF ENTRIES PROCESSED WAS: 


AIX.1 

ALIAS..1 

CLUSTER.2 

DATA. 3 

GOG.1 

INDEX..3 

NONVSAM.2 

PAGESPACE -.—0 

PATH.1 

SPACE.-.-1 

USERCATAL03.0 

TOTAL.15 


THE NUMBER OF PROTECTED ENTRIES SUPPRESSED MAS 0 
IDC0001I FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 0 
IDC0002I IDCAMS PROCESSING COMPLETE. MAXIMUM CONDITION CODE WAS 0 


Figure 16 (Part 2 of 2). Example of LISTCAT HISTORY Output 
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LISTCAT CREATION/EXPIRATION OUTPUT LISTING 


When you specify the LISTCAT command and include the CREATION or 
EXPIRATION parameter (or both)/ entries that have a creation or 
expiration date are selected according to the number of days you 
specify in the subparameter. 

In Figure 17/ for example/ because all entries in the listed 
catalog/ USERCAT3, were created on the same day as the LISTCAT/ 
no entries are listed as a result of the LISTCAT CREATI0NC5) 
job. When that job is run on an older catalog/ each entry whose 
creation date is prior to the number of days specified with the 
CREATION parameter is listed (that is/ the CREATION number of 
days specifies that all objects in the catalog at least 5 days 
old are to be listed). The creation date of the data and index 
objects of a cluster or alternate index is always the same as 
the creation date of its associated cluster or alternate index 
object. The creation date of the data and index object of a 
catalog is always set to 0. 

When you list all entries of a catalog/ and you specify the 
CREATION parameter/ each user catalog connector entry and each 
alias entry are also listed regardless of their creation date. 

When the LISTCAT EXPIRATION(20) job is run/ each entry whose 
expiration date occurs within 20 days of today's date is listed. 
Because the expiration date of a cluster or alternate index is 
controlled by the cluster or alternate index object entry in the 
catalog/ the expiration date for the data and index objects of a 
cluster or alternate index is always 0. 

When you list all entries of a catalog and you specify the 
EXPIRATION parameter, each volume entry will be listed/ because 
volume entries have no expiration date. 

These types of entries can have a creation or expiration date: 
ALTERNATEINDEX/ PATH/ CLUSTER/ DATA/ INDEX/ NGNVSAM, GDG, and 
PAGESPACE. 


/X LIST EACH CATALOG ENTRY WHOSE CREATION DATE X/ 

/X IS 5 DAYS AGO OR GREATER (THAT IS, THE OBJECT X/ 

/X IS AT LEAST 5 DAYS OLD). X/ 

LISTCAT - 

CREATI0N(5) - 
CAT A L OG(MJ KCAT) 


LISTING FROM CATALOG -- MJKCAT 


ALIAS - MJK.GDG1.ALIAS 

Figure 17 (Part 1 of 2). Example of LISTCAT CREATION/EXPIRATION Output 
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LISTING FROM CATALOG -- USERCAT3 



THE NUMBER OF ENTRIES PROCESSED WAS> 


AIX-0 

ALIAS-1 

CLUSTER -0 

DATA-0 

GDG-0 

INDEX-0 

NONVSAM -0 

PAGESPACE -0 

PATH-0 

SPACE-0 

USERCATALOG -0 

TOTAL-1 


THE NUMBER OF PROTECTED ENTRIES SUPPRESSED WAS 0 

IDC0001I FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 0 

/* LIST EACH CATALOG ENTRY WHOSE EXPIRATION DATE X/ 

/X IS WITHIN 20 DAYSX/ 

LISTCAT - 

EXPIRATION(20) - 
CATALOG(MJKCAT) 


LISTING FROM CATALOG — USERCAT3 

AIX - MJK.ALT.INDEX1 

DATA - MJK.ALT.INDEX1.DATA 

INDEX-MJK. ALT. INDEX1. INDEX ,<■ % 

PATH-MJK. AIXI. PATH 'v .%£ 

ALIAS - MJK.GDG1.ALIAS 

NONVSAM - MJK.NONVSAM1 

VOLUME - 333001 


LISTING FROM CATALOG — USERCAT3 
THE NUMBER OF ENTRIES PROCESSED WAS: 


AIX-1 

ALIAS-1 

CLUSTER -0 

DATA-1 

GDG-0 

INDEX-1 

NONVSAM --1 

PAGESPACE -0 

PATH-1 

SPACE-1 

USERCATALOG -0 

TOTAL-7 


THE NUMBER OF PROTECTED ENTRIES SUPPRESSED WAS 0 
IDC0001I FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 0 
IDC0002I IDCAMS PROCESSING COMPLETE. MAXIMUM CONDITION CODE WAS 0 
Figure 17 (Part 2 of 2). Example of LISTCAT CREATION/EXPIRATION Output 
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EXAMPLES OF LISTCAT IN A TSO ENVIRONMENT 


The following examples illustrate the output produced at a TSO 
terminal for a LISTCAT NAMES (default) and LISTCAT VOLUME. A 
TSO logon ID of IBMUSER is assumed. 

For LISTCAT NAMES, the catalog name is printed, followed by the 
names of all entries that have a high-level qualifier equal to 
the USER logon ID. 

For LISTCAT VOLUME, all entrynames that have a high-level 
qualifier equal to the USER logon ID are printed, followed by 
the volume serial numbers for those entries that contain volume 
information. 

Note: Because volume serial numbers for a cluster or an 

alternate index are contained in the data and index components, 
the data and index must have been named on the initial DEFINE in 
order to list the volume serial numbers. 

LOGON IBMUSER 


READY 

LISTCAT 

IN CATALOG! AMAST1 
IBMUSER.AIX 
IBMUSER.AIXDATA 
IBMUSER.AIXIDX 
IBMUSER.GDG 
IBMUSER.GDG.G0001V00 
IBMUSER.GDG.G0002V00 
IBMUSER.GDG.G0003V00 
IBMUSER.KSDS 
IBMUSER.KSDSDATA 
IBMUSER.KSDSIDX 
IBMUSER.NVSAM1 
IBMUSER.NVSAM2 
IBMUSER.NVSAM3 
IBMUSER.NVSAM4 
IBMUSER.NVSAM5 
READY 

LISTCAT VOLUME 

IBMUSER.AIX 
IBMUSER.AIXDATA 
—VOLUMES— 

333001 

IBMUSER.AIXIDX 
—VOLUMES— 

333001 
IBMUSER.GDG 
IBMUSER.GDG.G0001V00 
—VOLUMES— 

333001 

333002 

333003 

IBMUSER.GDG.G0002V00 
—VOLUMES— 

333004 

333005 

333006 

333007 

333008 

IBMUSER.GDG.G0003V00 
—VOLUMES— 

333009 

333010 

IBMUSER.KSDS 
IBMUSER.KSDSDATA 
—VOLUMES— 
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333001 

IBMUSER.KSDSIDX 
—VOLUMES— 
333001 

IBMUSER.NVSAM1 
—VOLUMES— 
333001 
333002 

IBMUSER.NVSAM2 
—VOLUMES— 
333003 
333004 
333005 

IBMUSER.NVSAM3 
—VOLUMES— 
333006 

IBMUSER.NVSAM4 
—VOLUMES— 
333007 

IBMUSER.NVSAM5 
—VOLUMES— 
333008 
333009 
333010 
333011 
333012 

READY 
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APPENDIX B#INTERPRETINGLISTCRA OUTPUT LISTINGS 


When you code the LISTCRA command, you can specify options that 
allow you to tailor the contents of the LISTCRA output. This 
appendix illustrates the various types of LISTCRA output, the 
order in which entries are listed, and the meanings of the 
listed fields. 


There are five kinds of LISTCRA listings. Four are illustrated 
in this appendix; the fifth, SEQUENTIALDUMP, is the same as that 
for DUMP NOCOMPARE, except that the entries are not sorted into 
groups. 

Each listed entry is identified by type (that is, by cluster, 
non-VSAM, and so on) and by name . Entries are usually listed in 
alphabetic order within groups of entries, according to 
entryname (except for SEQUENTIALDUMP). However, if insufficient 
virtual storage is available for the sorting operation, the 
records are listed as they appear in the catalog recovery area. 

On the listing, entries are sorted into three groups (except for 
a SEQUENTIALDUMP listing): 

• VSAM entries (which are also sorted according to entryname). 
Cluster entries, alternate index entries, and their 
associated data, index, and path entries are within this 
group. 

• Other entries that are sorted according to entryname. User 
catalog connector entries and non-VSAM entries are in this 
group. 

• Unsorted entries: other entries that are not sorted 
according to entryname. Entries that are listed within this 
group depend on the type of LISTCRA listing requested. 

The following list contains the abbreviation, type, and 
description for each kind of entry that can be listed as a 
result of the LISTCRA command: 


Abbreviation 


AIX 

ALIA 

CLUS 

DATA 

FRSP 

GDGB 

INDX 

NONV 

OEXT 

PATH 

UCAT 

UPGD 


Type 

G 

X 

C 

D 

F 

B 

I 

A 

E 

P 

U 

Y 


Description 
Alternate index entry 
Alias entry 
Cluster entry 
Data component entry 
Freespace entry 
Generation data group entry 
Index component entry 
Non-VSAM data set entry 

Extension record for an entry other than 
a volume entry 

Path entry 

User catalog connector entry (in the 
master catalog only) 

Upgrade set entry 
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Abbreviation 

VEXT 

VOL 


The five kinds of LISTCRA listings are: 

• NAME NOCOMPARE—This is the default option. Each entryname, 
its volumes, and the name and volumes of each related entry 
are listed. Within the "unsorted entries" group, all 
catalog records not yet printed are printed. See Figure 18 
on page 306. 

• DUMP NOCOMPARE—When DUMP is specified (NOCOMPARE is a 
default), each record is listed in the dump format. In 
addition, the name and volumes of each indirectly related 
entry are also listed. Within the "unsorted entries" group, 
the CRA f s self-describing records (control intervals through 
8) are printed, and any free space records and records not 
yet printed are printed. See Figure 19 on page 309. 

• NAME COMPARE—When COMPARE is specified (NAME is a default), 
only the name of each miscompared catalog entry is listed. 

A miscompared catalog entry is one whose information is not 
identical to the information contained in the entry*s copy 
in the catalog recovery area. A MISCOMPARE message is 
printed that identifies the most serious level of 
miscomparison. Within the "unsorted entries" group, 
miscompared records not yet printed out are printed. See 
Figure 20 on page 312. 

• DUMP COMPARE—When DUMP and COMPARE are specified, only the 
records (in dump format) of each miscompared catalog entry 
are listed. A miscompared catalog entry is one whose 
information is not identical to the information contained in 
the entry*s copy in the catalog area. For each entry, the 
catalog recovery area copy is listed first, followed by the 
catalog entry, followed by a line that contains asterisks to 
identify each miscompared byte. Following each entry, a 
MISCOMPARE message is printed that identifies the most 
serious level of miscomparison. Within the "unsorted 
entries" group, miscompared records not yet printed out are 
printed in the dump format. See Figure 21 on page 313. 

Note: As explained above, all MISCOMPARE messages result 

from a comparison between the catalog and the CRA. If the 
comparison shows that the catalog and CRA records are not 
identical, no inference is given as to which is correct. 

You must make this determination yourself by looking at 
other mismatches in the same listing and by examining 
related records in the catalog or CRA. 

• SEQUENTIALDUMP—When SEQUENTIALDUMP is specified, each 
record in the catalog recovery area is printed. The format 
of the output is the same as that of the DUMP NOCOMPARE, 
except that the entries are not sorted into groups or 
alphabetic sequence. 

See Catalog,,Ri P .gn ffS for a complete description 
of catalog recovery area record formats, catalog record 
formats, and relationships between catalog records. 


Type Description 

W Extension record for a volume entry 

V Volume entry 


1 


if 

i 4 

X 
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JOB CONTROL LANGUAGE (JCL) FOR LZSTCRA JOBS 


The job control language (JCL) statements that can be used to 
list catalog recovery areas are: 


//LISTCAT 

JOB 

• • • 

//STEP1 

EXEC 

PGM=IDCAMS 

//STEPCAT 

DD 

DSN=YOURCAT , DISP=SHR 

//CATDD 

DD 

DSN=YOURCAT,DISP=OLD 

//CRADD1 

DD 

VOL=SER=333001,UNIT=DISK,DISP=OLD 

//CRADD2 

DD 

VOL=SER=333002,UNIT=DISK,DISP=OLD 

//OUTDD 

DD 

DSN=LISTCRA.OUTPUT , UNIT=TAPE, 

// 

V0L = 

SER=TAPE10,LABEL=(1,NL),DISP=CNEW,KEEP), 

// 

DCB = 

CRECFM=VBA,LRECL=125, BLKSIZE=629) 

//SYSPRINT 

DD 

SYSOUT=A 

//SYSIN 

DD 

X 


LISTCRA - 
COMPARE - 
DUMP - 

INFILE(CRADD1/CRADD2) - 
CATALOGCYOURCAT/PASSWORD CATDD) - 
MASTERPWCSECRET) - 
OUTFILE(OUTDD) 

/x 

The JOB statement contains user and accounting information 

required for your installation. 

The EXEC statement identifies the program to be executed/ IDCAMS 

(that is, the access method services program). 

• STEPCAT DD/ which allocates your catalog. This is only 
required if the COMPARE option is specified. The catalog 
must be open as a catalog before it can be opened as a data 
set through the DD statement that so identifies it for the 
comparisons. 

• CATDD/ which specifies the catalog to be opened as a data 
set and compared to the catalog recovery areas. This is 
only required if the COMPARE option is specified. 

• CRADD1/ which specifies a volume whose catalog recovery area 
(CRA) is to be listed. 

• CRADD2/ which specifies another volume whose CRA is to be 
listed. 

• OUTDD/ which specifies an alternate output file, so that the 
LISTCRA output can be written onto an auxiliary storage 
device. The LISTCRA command's OUTFILE parameter points to 
the OUTDD DD statement. Only the LISTCRA output is written 
to the alternate output device. JCL statements/ system 
messages/ and job statistics are written to the SYSPRINT 
output device. 

— DSN=LISTCRA.OUTPUT specifies the name for the magnetic 
tape file. 

UNIT=TAPE and VOL=SER=TAPE10 specify that the file is to 
be contained on magnetic tape volume TAPE10. 

— LABEL=(1/NL) specifies that this is the first file on a 
nonlabeled tape. You can also use a standard-labeled 
tape by specifying LABEL=(1/SL). If subsequent job 
steps produce additional files of LISTCRA output on the 
same tape volume/ you should increase the file number in 
each job step's LABEL subparameter (that is, 

LABEL=(2/NL) for the second job step, LABEL=(3/NL) for 
the third job step, and so on). 

— DISP=(NEW/KEEP) specifies that this is a new tape file 
and is to be rewound when the job finishes. If a 
subsequent job step prints the tape/ DISP=(NEW/PASS) 
should be specified. If your job step contains more 
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than one LISTCRA command, DISP=(M0D,KEEP) or 
DISP=(M0D,PASS) can be used to concatenate all of the 
LISTCRA output in one sequential file. 

DCB=(RECFM=VBA,LRECL=125,BLKSIZE=629) specifies that the 
LISTCRA output records are variable length, blocked 
5-to-l, and are preceded by an ANSI print-control 
character. 

• SYSPRINT DD, which is required for each access method 
services job step. It identifies the output queue, 

SYSGUT=A, on which all LISTCRA output and system output 
messages are printed (unless the OUTFILE parameter and its 
associated DD statement is specified; see OUTDD above). 

Note: If you want all output to be written to an auxiliary 

storage device, replace 'OUTDD 1 with 'SYSPRINT' in the OUTDD DD 
statement and omit the SYSPRINT DD SYSGUT=A statement. 

• SYSIN DD, which specifies, with an asterisk OO, that the 
statements that follow are the input data statements. A 
'/X' terminates the input data statements. 

The LISTCRA command parameters shown above are common to the 
LISTCRA DUMP COMPARE example that follows. Other LISTCRA 
parameters may be coded and the output that results is 
illustrated. 

COMPARE, which specifies that the CRA entries are to be compared 
with the catalog entries identified by the CATALOG parameter. 
Only those that miscompare will be listed. 

DUMP, which specifies that each listed entry is to be printed in 
its entirety in both hexadecimal and character form. 

INFILE, which specifies the two DD statements, CRADD1 and 
CRADD2, which identify the two volumes whose CRAs are to be 
compared with the catalog entries and the miscomparing entries 
listed. 



CATALOG, which identifies the DD statement, CATDD, which 
identifies the catalog, YOURCAT, whose entries are to be 
compared with those in the CRAs. If the catalog is password 
protected, its master password, PASSWORD, is required. 

MASTERPW, which specifies the master password of the master 
catalog, SECRET, to enable the CRAs to be QPENed. 

OUTFILE, which points to the OUTDD DD statement. The OUTDD DD 
statement allocates an alternate output file for the LISTCRA 
output. 


If you want to print the LISTCRA output that is contained on an 
alternate output file, you can use the IEBGENER program. The 
following shows the JCL required to print the alternate output 
file, LISTCRA.OUTPUT, that was allocated previously* 


//PRINTOUT 

JOB 

... 

//STEP1 

EXEC 

PGM=IEBGENER 

//SYSUT1 

DD 

DCB= 

DSN=LISTCRA.OUTPUT,UNIT=TAPE, 
(RECFM=VBA,LRECL=125,BLKSIZE=629) 

//SYSUT2 

DD 

SYS0UT=A 

//SYSPRINT 

DD 

SYS0UT=A 

//SYSIN 

/* 

// 

DD 

DUMMY 


d ."\ 

vy 
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LISTCRA OUTPUT LISTING 


When you specify LISTCRA with no parameters/ each entryname, its 
volumeCs)/ and the name and volume(s) of each related entry are 
listed. The same listing would result if the NAME and NOCOMPARE 
parameters were specified. 

You can use this type of listing to list the name of each 
catalog entry whose copy is in the catalog recovery area/ and to 
determine the number of entries in each catalog recovery area. 
The total number of entries is an approximate size, in records/ 
of the catalog recovery area. 
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LISTING OF CATALOG RECOVERY AREA FOR VOLUME — 333301 — VSAM ENTRIES 

VOL - 333301 

CRAVOLRCD - 10/07/74 23:35:00 

F4DSCBVSAM - 10/07/74 23:35:00 

F4DSCBDUMP - 10/07/74 23:35:00 

CLUS - AA.LISTCRA.ESDS 

DATA - TF41C9A0.VSAMDSET.DFD74280.T861DAD4.TF41C9A0 
DATA VOL - 
333301 

AIX - AA2.LR.ESDS 
DATA VOL - 
333301 
INDX VOL - 
333301 

AIX - AA1.LR.ESDS 
DATA VOL - 
333301 
INDX VOL - 
333301 

PATH - AAU.LR.ESDS 

UPGD - 

CLUS - AA.LISTCRA.KSDS 

DATA - T5C55DD0.VSAMDSET.DFD74280.T861DB0A.T5C55DD0 
DATA VOL - 
333301 

INDX - T5C56E70.VSAMDSET.DFD74280.T861DB0A.T5C56E70 
INDX VOL - 
333301 

AIX - AA1.LR.ESDS 

DATA - TCD41020.VSAMDSET.DFD74280.T861DB23.TCD41020 
DATA VOL - 
333301 

INDX - TCD41F00.VSAMDSET.DFD74280.T861DB23.TCD41F00 
INDX VOL - 
333301 

CLUS - AA.LISTCRA.ESDS 

PATH - AA1U.LR.ESDS 

PATH - AA1N.LR.ESDS 

CLUS - LR.MCKEYRNG.KSDS 

DATA - TF081480.VSAMDSET.DFD74280.T861DB0E.TFO8148O 
DATA VOL - HIGH KEY 

333301 - C1C1C1C1C1C1C1C1C5F9 
333301 - C1C1C1C1C1C1C1C1E9E9 

INDX - TF082370.VSAMDSET.DFD74280.T861DB0E.TF082370 
INDX VOL - 
333301 
333301 


Figure 18 (Part 1 of 2). Example of LISTCRA NAME NOCOMPARE Output 
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LISTING OF CATALOG RECOVERY AREA FOR VOLUME — 333301 ~ OTHER ENTRIES 

UCAT - USERCAT2 
DATA VOL - 
333304 

NUMBER OF ENTRIES PROCESSED 
CLUS - 3 

DATA - 4 

AIX - 1 

INDX - 2 

PATH - 3 

VOL - 1 

UPGD - 1 

SUM - 15 


Figure 18 (Part 2 of 2). Example of LISTCRA NAME NOCOMPARE Output 


LISTCRA NAME NOCOMPARE Output Notes: 

• The title line of the output contains the volume serial 
number and identifies the group that the following entries 
are within (in this case , VSAM Entries). 

• The time stamps: 

CRAVOLRCD is the timestamp of the CRA volume record. It is 
updated only when the first catalog record and first CRA 
volume record are updated/ after the CRA is opened when VSAM 
is running. (Note: If the volume is moved to a DOS/VS 
system and used there, the CRAVOLRCD timestamp is updated 
each time the catalog and CRA volume records are updated for 
a space allocation change). 

F4DSCBVSAM is a timestamp in the format-4 DSCB, and is 
updated in the same manner as the CRAVOLRCD timestamp. 

F4DSCBDUMP is also a timestamp in the format-4 DSCB, and is 
updated in the same manner as the CRAVOLRCD timestamp. It 
is also updated whenever the operating system utility 
program IEHDASDR dumps the volume. 

• VSAM entries are listed along with the entryname and 
volume(s) of each related entry. 

• Paths are shown as related only to the entry to which the 
path provides access. A path that serves as an alias for a 
VSAM data set is listed with the data-set*s entry. A path 
that shows the relationship of an alternate index to a base 
cluster is listed with the alternate-index f s entry only. 

• UPGD indicates that there are alternate indexes in the 
base-clusters upgrade set. If you want to identify the 
indexes in the upgrade set, use the DUMP NOCOMPARE option. 

• The high-key value of each keyrange is shown. 

• SUM is the total number of catalog recovery area entries 
printed. 
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LISTCRA DUMP OUTPUT LISTING 


When you specify LISTCRA with the DUMP parameter, each record in 
the catalog recovery area is listed in dump format. In 
addition, the name and volumes of each indirectly related entry 
are also listed. The same listing would result if the DUMP and 
NOCOMPARE parameters were specified. 

When you specify LISTCRA SEQUENTIALDUMP, the same listing 
results, except that the records are listed in their entry 
sequence within the catalog recovery area. 

You can use this type of listing to list the complete contents 
of each catalog entry whose copy is in the catalog recovery 
area, and to determine the exact number of entries and records 
in each catalog recovery area. 
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LISTING OF CATALOG RECOVERY AREA FOR VOLUME -- 113301 -- VSAM ENTRIES 


ot jooooocl 
00000000 
00000000 
1152A820 
00000000 
86000100 
05000037 
00378800 
88001000 
1500003E 
003E8800 
08002000 
46000C00 
B23FOOOO 


01F3F3F3 
00000000 
00000000 
00305020 
2600003E 
00378800 
88000600 
0B0O00 37 
00378800 
88001600 
1BOOOOOO 
00 3C0800 
005486ID 
4C000C00 


F3F0F10O| 
00000000 
00000000 
09000032 
00000000 
01000037 
00480800 
88OOOCOO 
11000037 
00 3E8800 
08001COO 
21000C00 
B2050000 
0058861D 


,0009 3050 
~E5b 1BDOO 
00000000 
E6019B00 
000D8500 
88000200 
07000037 
00378800 
88001200 
1700003E 
000C0800 
005186 ID 
4700GC00 
B23FOOOO 


2 0Qjfbo 1D 8A4E0000 00000000 00000000 
7F T3F3F3 f'3F0F1Q01 00000000 00000000 
00000000 00000000 OOOOOOOO 0086IDEE 
13336DBF BF380002 00000500 OOOOOOOO 
0100000E 85000200 OOOF85UO 03000037 
00378800 03000037 88000400 00378800 
88000800 00378800 09000037 88000A00 
00000037 880O0E00 00378800 OF000037 
00378800 1300003E 88001400 003E8800 
88001800 003E8800 1900003E 88001A00 
1D000018 08001E00 00240800 1F000030 
B1D60000 42000C00 005286ID B1D60000 
005586ID B2050000 48000C00 005786ID 
5QOOOCOO 006086ID B79COOOO 2C1DB173 




I'LUS - KSDS01 

OOOOOE 00000017 01F3F3F3 F3F0F1OO 000E3050 200986|fc 8A4EOOOO OOOOOOOO OOOOOOOO 

♦| 0020j OOOOOOOO OOOOOOOO OOOOOOOO C300A800 6( ±>2E2C4 E2F0Fl40l 40404040 40404040 

0040140404040 40404040 40404040 40404040 40404040 40404040 40404040 40FFFFFF 


0060 FFFFFFFF FF74280F OOOOOFOO OOOOOOOO 
0080| 0200000C 020 30000 12020400 00004401 


00070000 OOCOOOOO 00000201 00006024 
0006C400 00180006 C9000019 0006D900 


I OOAOI 001A0006 C700001B OOOOOOOO OOOOOOOO OOOOOOOO OOOOOOOO OOOOOOOO OOOOOOOO 
DATA * T188D0C0.VSAMDSET.DFD74280.T861D99E.T188D0C0 

OOOOD 00000018 01F3F3F3 F3F0F100 000D3050 2009861D 8A4E861D 99E20000 OOOOOOOO 

0020 OOOOOOOO OOOOOOOO OOOOOOOO C4016200 8FE3F1F8 F8C4F0C3 F04BE5E2 C1D4C4E2 

0040 C5E34BC4 C6C4F7F4 F2F8F04B E3F8F6F1 C4F9F9C5 4BE3F1F8 F8C4F0C3 FOFFFFFF 

0060 FFFFFFFF FF74280F OOOOOOOO 20000000 22000000 01000001 80000000 00000030 

0080 OOOOOOOF F90000FF FFFFFFFF FFFFFFOO OOOOOOOO 06000000 COOOOOOO 00010100 

OOAO 00620201 0000A902 02000068 03010000 00440100 62608000 60000000 03001400 

OOCO 00000300 OOOOOOOO 00000010 OOOOOOOF F9000000 OOOOOOOO OOOOOOOO OOOOOOOO 

00EO OOOOOOOO OOOOOOOO OOOOOOOO OOOOOOOO 01000000 OOOOOOOO OOOOOOOO OOOOOOOO 

0100 OOOOOOOO 000000 30 OOOOOOOO OOOOOOOO OOOOOOOO 000006C 3 0000170 3 27 305020 

0120 09F3F3F3 F3F0F100 00800100 OOOOOOOO OOOOOOOO 00300000 00100000 03000140 

0140 00010000 00000014 00010002 00000002 00000001 OOOOOOOO 00002FFF 0006E800 

0160 00150000 OOOOOOOO OOOOOOOO OOOOOOOO OOOOOOOO OOOOOOOO OOOOOOOO OOOOOOOO 

INDX - T188E190.VSAMDSET.DFD74280.T861D99E.T188E190 

OOOOF 00000019 01F3F3F3 F3F0F100 000F3050 2009861D 8A4E861D 99E20000 OOOOOOOO 

0020 OOOOOOOO OOOOOOOO OOOOOOOO C9015700 8FE3F1F8 F8C5F1F9 F04BE5E2 C1D4C4E2 

0040 C5E34BC4 C6C4F7F4 F2F8F04B E3F8F6F1 C4F9F9C5 4BE3F1F8 F8C5F1F9 FOFFFFFF 

0060 FFFFFFFF FF74280F OOOOOOOO 2000FFFF FFFFOOOO 01000001 80000000 00000028 

0080 OOFFFFFF FFOOOOFF FFFFFFFF FFFFFFOO OOOOOOOO 05000000 COOOOOOO 00010100 

OOAO 00620201 00006803 01000000 44010062 60000060 00010003 00140000 00140000 

00 CO OOOOOOOO 00000200 000001F9 OOOOOOOO OOOOOOOO OOOOOOOO OOOOOOOO OOOOOOOO 

OOEO OOOOOOOO OOOOOOOO 00000001 OOOOOOOO OOOOOOOO OOOOOOOO OOOOOOOO OOOOOOOO 

0100 00002800 OOOOOOOO OOOOOOOO OOOOOOOO 0006C300 00170327 30502009 F3F3F3F3 

0120 FOF10000 80010000 OOOOOOOO OOOOOOOO 28000000 02000014 00140000 02000000 

0140 00001400 01000200 01000200 01000100 OOOOOOOO 0027FF00 OOOOOOOO OOOOOOOO 


3330H . . .t.+ . . . 

.C...(KSDSO1 


. 333301 _&.♦ . . .S. 

.D_T188D0C0. VSAMDS 

ET.DFD74280.T861D99E.T188D0C0... 


. 333301 _l.♦ . . .S. 

.I_T188E190.VSAMDS 

ET.DFD74280.T861D99E.T188E190... 


.C.1. . 3333 


000010 000000 1 A 01F3F3F3 F3F0F100 00100000 
0020 OOOOOOOO OOOOOOOO OOOOOOOO D9009800 
0040 40404040 40404040 40404040 40404040 
0060 FFFFFFFF FF74280F OOOOOFSO OOOOOOOO 
0080 0200000C 02030006 C3000017 0006C400 


000086ID 8A4E0000 OOOOOOOO OOOOOOOO 
6CD7C1E3 C8F0F140 40404040 40404040 
40404040 40404040 40404040 40FFFFFF 
OOOOOOOO OOCOOOOO 00000201 00000602 
00180006 C9000019 OOOOOOOO OOOOOOOO 


. 333301.4. . 

.R...(PATH01 


Figure 19 (Part 1 of 2). Example of LISTCRA DUMP NOCOMPARE Output 
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AIX - AIX01 
DATA VOL - 

-* 333301 

INDX VOL - 


000014 000000iy01F3F 
0020 0000000# 00000 
0040 01000*64]00001 


f f 

liyOlF3F3F3r F3F0F1 
>0# 0000000P 000000 


F3F0F100 00143050 
0000000 0 E8004B00 
OOOOlitK) 00000000 


200086ID 8A4E0000 00000000 00000000 
31000000 00000200 OOOOCOOO 00000002 


00000000 00000000 00000000 00000000 


DATA - TF081480.VSAMDSET.DFD74280.T861DB0E.TF081480 


000038 00000048 01F3F3F3 
0020 00000000 00000000 
0040 C5E34BC4 C6C4F7F4 
0060 FFFFFFFF FF74280F 
0080 00000000 500000FF 
OOAO 00620201 00006803 
OOCO 00001400 00000000 
OOEO 00000000 00000000 
0100 00000000 00000050 
0120 09F3F3F3 F3F0F100 
0140 0018000A C1C1C1C1 
0160 00040003 00040001 
0180 00000000 00002800 
01AO C1C6C100 0AC1C1C1 
01C0 0000004F FFOOOOOO 


F3F0F100 00383050 2009861D 
00000000 C401C500 8FE3C6F0 
F2F8F04B E3F8F6F1 C4C2F0C5 
00000000 20000000 06000000 
FFFFFFFF FFFFFFOO 00000000 
010000BD 03020000 00440100 
00000002 00000000 50000000 
00000000 00000000 02000000 
00000000 00000000 00000000 
00800100 00000000 00000000 
C1C1C1C1 C1C1000A C1C1C1C1 
00000000 000027FF 03273050 
00005000 00000200 00140009 
C1C1C1C1 C1E9E900 14000100 
00000000 00000000 00000000 


8A4E861D BOFOOOOO 00000000 
F8F1F4F8 F04BE5E2 C1D4C4E2 
4BE3C6F0 F8F1F4F8 FOFFFFFF 
01000001 80000000 00000050 
06000000 COOOOOOO 00010100 
62608400 60000000 OAOOOAOO 
00000000 00000000 00000000 
00000000 00000000 00000000 
000006C3 00004703 27305020 
00280000 00020000 14000140 
C1C1C1C1 C5F90014 00010003 
2009F3F3 F3F3FOF1 00008001 
40001800 0AC1C1C1 C1C1C1C1 
03000500 03000500 01000028 
00000000 00000000 00000000 



6.C.6. 



AFA..AAAAAAAAZZ 


INDX - TF082370.VSAMDSET.DFD74280.T861DB0E.TF082370 


00003A 00000049 01F3F3F3 F3FOF100 003A3050 2009861D 8A4E861D BOFOOOOO 00000000 _.333301 _S,.■*■...0. 

0020 00000000 00000000 00000000 C9018900 8FE3C6F0 F8F2F3F7 F04BE5E2 C1D4C4E2 .I....TF082 370.VSAMDS 

0040 C5E34BC4 C6C4F7F4 F2F8F04B E3F8F6F1 C4C2F0C5 4BE3C6F0 F8F2F3F7 FOFFFFFF ET.DFD74280.T861DBOE.TF082370... 

0060 FFFFFFFF FF74280F 00000000 2000FFFF FFFFOOOO 01000001 80000000 00000028 . 

0080 OOFFFFFF FFOOOOFF FFFFFFFF FFFFFFOO 00000000 06000000 COOOOOOO 00010100 . 

OOAO 00620201 00006803 010000A9 03020000 00440100 62600400 60000400 OAOOOAOO .. 

OOCO 00001400 00000000 00000002 00000001 F9000000 00000000 00000000 OOOOOOOO ..'...9. 

OOEO OOOOOOOO OOOOOOOO OOOOOOOO OOOOOOOO 01000000 OOOOOOOO OOOOOOOO OOOOOOOO .; 

0100 OOOOOOOO 00000028 OOOOOOOO OOOOOOOO OOOOOOOO 000006C3 00004703 27305020 .0.&. 

0120 09F3F3F3 F3F0F100 00800100 OOOOOOOO OOOOOOOO 00280000 00020000 14000140 .333301. 

0140 00190000 00000014 00010003 00060003 00060001 OOOOOOOO 000027FF 03273050 .& 

0160 2009F3F3 F3F3FOF1 00004000 OOOOOOOO OOOOOOOO OOOOOOOO 00000200 00140001 ..333301 . 

0180 40001900 OOOOOOOO OOOOOOOO OOOOOOOO OOOOOOOO OOOOOOOO OOOOOOOO OOOOOOOO . 


iTX 

Xy 


Figure 19 (Part 2 of 2). Example of LISTCRA DUMP NOCOMPARE Output 


LISTCRA DUMP NOCOMPARE Output Notes: 

Note: When you specify SEQUENTIALDUMP, the same information is 

listed. The entries are not sorted according to type of entry, 

or according to alphanumeric-sequence of the entryname field. 

See also Note 7, below. 

1. The 3-byte CRA control interval number, in hexadecimal form. 

2. The 3-byte control interval number of the catalog record for 
which this is a copy, in hexadecimal form. 

3. The entrytype at offset X f 2C f (decimal 44), a character that 
identifies the type of catalog entry being listed. 

4. A 44-byte field at offset X , 31 l (decimal 49) that contains 
the entry’s entryname (padded with binary zeros), or an 
8-byte field followed by 36 bytes of binary zeros that 
contain the volume entry’s volume serial number. 

5. The volume serial number of the recovery volume. 

6. A 2-byte displacement value. Printing is suppressed after 
the last line containing data is listed, even though all 
catalog records are 512 bytes long. 

7. As in the NAME NOCOMPARE output, the alternate index name 
and the fact that there is an upgrade set is given, along 
with the volume serial numbers of the alternate index’s data 
and index components. (Note: If SEQUENTIALDUMP is 
specified, the information described with this note is not 
listed.) 
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8. The first byte identifies the alternate index's data 
component and the next three bytes contain its catalog 
control interval number. 

9. The first byte identifies the alternate index's index 
component and the next three bytes contain its catalog 
control interval number. 

10. Because there are two key ranges for this cluster, there are 
two volume information sets of fields in the cluster's data 
and index component entries. 
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LXSTCRA COMPARE OUTPUT LISTING 


When you specify LISTCRA with the COMPARE parameter, each record 
in the catalog recovery area is compared with its original in 
the catalog. The name of each catalog entry that miscompares is 
listed. A miscompared catalog entry is one whose information is 
not identical to the information contained in the entry's copy 
in the catalog recovery area. The same listing would result if 
the NAME and COMPARE parameters were specified. 

You can use this type of listing to determine the number of 
damaged entries in your catalog, and you can get an idea of the 
type of damage that occurred to each entry. You can issue the 
EXPORTRA and IMPORTRA commands to recover the catalog and make 
its damaged entries usable. 


LISTING OF CATALOG RECOVERY AREA FOR VOLUME — 333301 -- VSAM ENTRIES 


CATVOLRCD - 09/17/42 
CRAVOLRCD - 10/07/74 
F4DSCBVSAM - 10/07/74 
F4DSCBDUMP - 10/07/74 


23:53:47 

23:35:00 

23:35:00 

23:35:00 


CLUS - LR.DELETED.ESDS 


* MISCOMPARES - CATALOG ENTRY HAS DIFFERENT NAME 


CLUS - LR.MCHURBA.ESDS 


DATA - T73FEDA0.VSAMDSET.DFD74280.T861DAE1.T73FEDA0 
DATA VOL - 
333301 

* MISCOMPARES - HIGH USED RBA 


CLUS - LR.MCKEYRNG.KSDS 

DATA - TF081480.VSAMDSET.DFD74280.T861DB0E.TF081480 
DATA VOL - HIGH KEY 

333301 - C1C1C1C1C1C1C1C1C5F9 
333301 - C1C1C1C1C1C1C1C1E9E9 

X MISCOMPARES - HIGH USED RBA 

INDX - TF082370.VSAMDSET.DFD74280.T861DBOE.TF082370 
INDX VOL - 
333301 
333301 

X MISCOMPARES - STATISTICS 

NUMBER OF ENTRIES PROCESSED 
CLUS - 23 
DATA - 18 
AIX - 8 

INDX - 11 
PATH - 5 

VOL - 1 

UPGD - 3 

SUM - 69 


IDC0665I 

NUMBER 

OF 

ENTRIES 

THAT 

MISCOMPARED 

IN 

THIS 

CRA 

IDC0877I 

NUMBER 

OF 

RECORDS 

THAT 

MISCOMPARED 

IN 

THIS 

CRA 

Figure 20. 

Example 

of 

LISTCRA 

NAME 

COMPARE Output 
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LISTCRA NAME COMPARE Output Notes 


• In addition to the timestamps described for the NAME 
NOCOMPARE output (noted previously), the timestamp in the 
catalog volume record, CATVOLRCD, is listed. CATVOLRCD is 
updated in the same manner as the CRAVOLRCD timestamp. 

• The MISCOMPARES message always refers to the record listed 
above it. See "Regaining Access to Data" in the Catalog 
Adm i nis .t ra .tA. Q J ) . 6 mI da for the cause and seriousness of this 
MISCOMPARES message. 

• The number of records is sometimes larger than the number of 
entries, because an entry might consist of a catalog record 
and one or more extension records that failed to compare 
correctly. 


LISTCRA DUMP COMPARE OUTPUT LISTING 

When you specify LISTCRA with the DUMP and COMPARE parameters, 
each record in the catalog recovery area is compared to its 
original in the catalog. Each catalog entry*s copy in the 
catalog recovery area that miscompares is listed, followed by 
its original catalog entry (which is damaged), followed by 
asterisks to indicate each miscompared byte. 

You can use this type of listing to determine the exact damage 
that occurred to each entry. You might be able to correct some 
or all of the damage by using the ALTER command. You can issue 
the EXPORTRA and IMPORTRA commands to recover the catalog and 
make its damaged entries usable. 


LISTING OF CATALOG RECOVERY AREA FOR VOLUME -- Hiidl -- VSAM ENTRIES 


CLUS - LR.MCHURBA.ESDS 

►000020 0000002C 01F3F3F3 
CATRCD 0000002C 01F3F3F3 

0020 00000000 00000000 
00000000 00000000 

0040 40404040 40404040 
40404040 40404040 

0060 FFFFFFFF FF74280F 
FFFFFFFF FF74280F 

0080 002D0000 00000000 
002D0000 00000000 


F3F0F100 00203060 
F3F0F100 00203050 

00000000 C3008200 
00000000 C3008200 

40404040 40404040 
40404040 40404040 

OOOOOFOO 00000000 
OOOOOFOO 00000000 

00000000 00000000 
00000000 00000000 


200986 ID 8A4E0000 OOOOOOOO OOOOOOOO 
200986ID 8A4E0000 0000000(1 OOOOOOOO 


6CD3D94B 

6CD3D94B 

40404040 

40404040 

OOOOOOOO 

OOOOOOOO 

OOOOOOOO 

OOOOOOOO 


D4C3C8E4 

D4C3C8E4 

40404040 

40404040 

00020100 

00020100 

OOOOOOOO 

OOOOOOOO 


D9C2C14B 

D9C2C14B 

40404040 

40404040 

00004401 

00004401 

OOOOOOOO 

OOOOOOOO 


C5E2C4E2 

C5E2C4E2 

40FFFFFF 

40FFFFFF 

0006C400 

0006C400 

OOOOOOOO 

OOOOOOOO 


3 3 3301 _ (, 



C. . . (LR.MCHURBA.ESDS 
(LR. MCHURBA. ESDS 


D 

D 


DATA - T73FEDAO.VSAMDSET.DFD74280.T861DAE 1.T73FEDAO 


000021 0000002D 01F3F3F3 
CATRCD 0000002D 01F3F3F3 


F3F0F100 00213050 
F3FOF100 00213050 


200986ID 8A4E861D AE2EOOOO OOOOOOOO 
200986ID 8A4E861D AE2EOOOO OOOOOOOO 


333301 _fc.+ 

333301 _ i .+ 


0020 

OOOOOOOO 

OOOOOOOO 

OOOOOOOO 

C4015700 

8FE4F7F3 

C6C5C4C1 

F04BE5E2 

C1D4C4E2 


OOOOOOOO 

OOOOOOOO 

OOOOOOOO 

C4015700 

8FE4F7F3 

C6C5C4C1 

F04BE5E2 

C1D4C4E2 

0040 

C5E34BC4 

C6C4F7F4 

F2F8F04B 

E3F8F6F1 

C4C1C5F1 

4BE3F7F3 

C6C5C4C1 

FOFFFFFF 


C5E34BC4 

C6C4F7F4 

F2F8F04B 

E3F8F6F1 

C4C1C5F1 

4BE3F7F3 

C6C5C4C1 

FOFFFFFF 

0060 

FFFFFFFF 

FF74280F 

OOOOOOOO 

20000000 

04000000 

01000001 

80000000 

00000028 


FFFFFFFF 

FF74280F 

OOOOOOOO 

20800000 

04000000 

01000001 

80000006 

00000028 

0080 

OOOOOOOO 

500000FF 

FFFFFFFF 

FFFFFFOO 

OOOOOOOO 

05000000 

OOOOOOOO 

00010100 


OOOOOOOO 

500000FF 

FFFFFFFF 

FFFFFFOO 

OOOOOOOO 

05000000 

(0000000 

00010100 

OOAO 

00620201 

00006803 

01000000 

44010062 

60000060 

OOOOOOOO 

OOOOOOOO 

00140000 


00620201 

00006803 

01000000 

44010062 

60000060 

OOOOOOOO 

OOOOOOOO 

00140000 


• MISCOMPARES - HIGH USED RBA 



.D_T7 3FEDA0. VSAMDS 

.D_T7 3FEDA0. VSAMDS 

ET.DFD74280.T861 DAE 1.T7 3FEDA0... 
ET.DFD74 280.T861DAE1.T7 3FEDA0. .. 


( 



Figure 21. Example of LISTCRA DUMP COMPARE Output 
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LISTCRA DUMP COMPARE Output Notes: 

1. The 3-byte CRA control interval number in hexadecimal form. 

2. Each pair of hexadecimal-data lines is the information in 
the catalog recovery area*s copy of the catalog record# 
followed by the information in the catalog record# for the 
same displacement. 

3. Asterisks are printed below the bytes in which a miscompare 
exists and# in the left margin# the miscompared lines are 
flagged with a single asterisk. 

4. See "Regaining Access to Data" in the Catalog Administration 
Guide for the cause and seriousness of this MISCOMPARES 
message. 
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AP P E N D !X , Ct_.SA MPL E Q U I EU.L..E K P M , Q HK LIST 


Figure 22 shows the format of output from the CHKLIST command. 

For each checkpoint entry listed under "CHECKID", the other 
columns give dsname, ddname, unit, and volume information for 
each tape data set that was open at the time of the checkpoint. 
Asterisks under "UNIT” indicate an unrecognizable unit type. 
"VOLUME X OF Y IS CURRENT" indicates the volume sequence number 
of the volume mounted at the time of the checkpoint and the 
total number of volumes in the data set. each volume f s volume 
serial number is listed, and an asterisk indicates the volume 
mounted at the time of the checkpoint. 


CHKLIST INPILE(CHKPT) CHECKID(C0000001 C0000002) 


IDCAMS SYSTEM SERVICES TIME: 21:34:43 01/16/75 


OPEN TAPE 

DATA SET LIST PROM CHECKPOINT DATA 

SET - CHKPT 

DATASET 




CHECKID 

DSNAME 

DDNAME 

UNIT 

VOLUMES 

- • INDICATES CURRENT VOLUME 

C0000001 

USER.TAPE.DATASETO 

DDN2VS11 

2400-7TRK 

VOLUME 

120001• 

1 OF 

1 IS CURRENT 



USER.TAPE.DATASET1 

DDN3VS11 

2400-9TRK 

VOLUME. 

3 OF 

4 IS CURRENT 






130001 

130002 

130003* 130004 



USER.TAPE.DATASET2 

DDN4VS11 

3400-7TRK 

VOLUME 

140001* 

1 OF 

1 IS CURRENT 


C0000002 

USER.TAPE.DATASET3 

DDNAME32 

2400-9TRK 

VOLUME 

8 OP 

8 IS CURRENT 






230001 

230002 

230003 230004 

230005 





230006 

230007 

230008* 



USER.TAPE.DATASET4 

DDNAME42 

2400-9TRK 

VOLUME 

20 OP 

24 IS CURRENT 






240001 

240002 

240003 240004 

240005 





240006 

240007 

240008 240009 

240010 





240011 

240012 

240013 240014 

240015 





240016 

240017 

240018 240019 

240020* 





240021 

240022 

240023 240024 



IDC0001I FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 0 
IDC0002I IDCAMS PROCESSING COMPLETE. MAXIMUM CONDITION CODE WAS 0 


Figure 22. Example of CHKLIST Output 
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AEEENPI X P,_CAUTIflMJEQR. ^C L. BP- P ARAM E TERS 


I 


Parameter 

AFF 

i 

CHKPT 

DATA 

DCB 

DISP 


Figure 23 



You should be aware that some specifications do nothing in a 
VSAM environment or might cause problems for you. Figure 23 
shows the DD statement parameters and subparameters to be 
avoided with VSAM. For more information* see JCL . 


Subparameter Comment 


ddname 


EOV 


All 


CAT LG 


DELETE 


MOD 


KEEP 


You must use this parameter carefully. If 
the cluster components (the data and its 
index) reside on unlike devices* the results 
of an AFF specification are unpredictable. 

Because checkpoints at end of volume are 
executed only for BSAM and QSAM data sets* 
this parameter does not apply to VSAM data 
sets and need not be coded. 

Because there is no way to get VSAM data into 
the input stream* this parameter is not 
applicable to VSAM. 

The access method control block (ACB)* not 
the DCB* describes VSAM data sets; therefore* 
the DCB parameter is not applicable to VSAM. 

An access method control block is generated 
by an ACB or GENCB macro* and can be modified 
by a MODCB macro. 

CATLGVSAM data sets are cataloged and 
uncataloged as a result of an access method 
services command* if CATLG is coded* a message 
is issued* but the data set is not cataloged. 

VSAM data sets are deleted as a result of an 
access method services command* if DELETE is 
coded* a message is issued* but the data set 
is not deleted. 

For VSAM data sets* MOD is treated as if OLD 
were specified* except for processing with an 
ISAM program* in which case MOD indicates 
resume load. 

Because KEEP is implied for VSAM data sets* 
it need not be coded. 


NEW VSAM data sets are initially allocated as 

a result of the access method services 
DEFINE command. If NEW is specified* space 
is allocated and it is never used 
by VSAM. Moreover* an access method services 
request for space may fail if the DISP=NEW 
acquisition of space causes too little space 
to remain available. 


(Part 1 of 3). JCL DD Parameters 
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Parameter 

Subparameter 

Comment 


UNCATL6 

VSAM data sets are cataloged and uncataloged 
as a result of access method services commands 
if UNCATLG is coded, a message is issued, but 
the data set is not uncataloged. 

DSNANE 

dsnameCareaname) 

The name is used; areaname is ignored. 


dsnameCgeneration) 

A generation data group entry must exist in 
the catalog for this to apply. 


dsnameCmember) 

The name is used; member is ignored. 


All temporary 
dsnames 

Because VSAM data sets are built by access 
method services, which uses the data set 
name supplied in the DEFINE command; 
temporary names cannot be used with VSAM. 


All backward 

DD references 
of the form 

X.ddname 

If the object referred to is a cluster and 
the data set and index reside on unlike 
devices, the results of a backward DD 
reference are unpredictable. 

LABEL 

BLPt NL, NSL 

Because these subparameters have no meaning 
for direct access devices, they do not apply 
for VSAM data sets, which all reside on 
direct access storage. 

IN 


Because IN is used to override DCB 
subparameters and the DCB parameter does not 
apply to VSAM data sets, IN does not apply. 

OUT 


Because OUT is used to override DCB 
subparameters and the DCB parameter does not 
apply to VSAM data sets, OUT does not apply. 

LABEL 

NOPWREAD 

PASSWORD 

The password protection bit is set for all 

VSAM data sets, regardless of the 
PASSWORD/NOPWREAD specification in the LABEL 
parameter. 


SL, SUL 


SEP ddname 


SPACE 


Although these parameters apply to 
direct access storage devices, SL is always 
used for VSAM, whether you specify SL, SUL, 
or neither. 

You must use this parameter carefully. If 
the cluster components, the data and its 
index, reside on unlike devices, the results 
of a SEP specification are unpredictable. 

VSAM data sets are initially allocated as a 
result of the access method services DEFINE 
command. Therefore, if SPACE is specified 
on the DD statement, an extent is allocated 
that is never used by VSAM. Moreover, an access 
method services request for space may fail 
as a result of the SPACE acquisition of space. 


Figure 23 (Part 2 of 3). JCL DD Parameters 
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Parameter Subparameter 
SYSOUT 

UCS All 

UNIT AFF 


UNIT SEP 


VOLUME REF 


volseq# 


Comment 

If SYSOUT is coded with a mutually exclusive 
parameter (for example, DISP), the job step 
is terminated with an error message. 

Because this parameter applies only to 

unit record devices, it does not apply to VSAM. 

You must use this subparameter carefully. 

If the cluster components, the data, and its 
index reside on unlike devices, the results 
of UNIT=AFF are unpredictable. 

You must use this subparameter carefully. 

If the cluster components, the data, and its 
index reside on unlike devices, the results 
of UNIT=5EP are unpredictable. 

You must use this subparameter carefully. 

If the referenced volumes are not a subset 
of those contained in the catalog record 
for the data set, the results are 
unpredictable. 

Results are unpredictable. 


volcount This subparameter is used to request some 

number of nonspecific volumes. Because all 
VSAM volumes must be specifically defined 
before processing, volcount is not applicable 
to VSAM data sets. 


Figure 23 (Part 3 of 3). JCL DD Parameters 
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Access method services can be invoked by a problem program 
through the ATTACH, LINK, or LOAD and CALL macro instructions. 

The dynamic invocation of access method services enables 
respecification of selected processor defaults as well as the 
ability to manage input/output operations for selected data 
sets. 


For information on APF authorization, see 
.Quids or ^SMJLd■ 


The following descriptions of the invoking macro instructions 
are related to Figure 24 on page 322, which describes the 
argument lists referenced by the invoking macros. 


LINK OR ATTACH MACRO INSTRUCTION 

Access method services may be invoked through either the LINK or 
the ATTACH macro instruction. 

The format of the LINK or ATTACH macro instruction is; 


Cg ams 3 


LINK|ATTACH 


EP=IDCAMS, 

PARAM= (ogti ojiaddc 
[,dnamsadd£l 
C f pgnoaddr 3 

tfialiffjaddcl 

VL=1 


EP=IDCAMS 

specifies that the program to be invoked is IDCAMS. 

PARAM= 

specifies the addresses of the parameters to be passed to 
IDCAMS. These values can be coded; 

Q£±i£lQa. <i dr 

specifies the address of an option list, which can be 
specified in the PARM parameter of the EXEC statement 
and is a valid set of parameters for the access method 
services PARM command. If you do not want to specify 
any options, this address must point to a halfword of 
binary zeros. Figure 24 on page 322 shows the format 
of the options list. 

dp.amg.ad.dr: 

specifies the address of a list of alternate dd names 
for standard data sets used during IDCAMS processing. 
If standard ddnames are used and this is not the last 
parameter in the list, it should point to a halfword 
of binary zeros. If it is the last parameter, it may 
be omitted. Figure 24 shows the format of the 
alternate ddname list. 

gsn& add r 

specifies the address of a 3~ to 6-byte area that 
contains an EBCDIC starting page number for the system 
output file. If the page number is not specified, but 
this is not the last parameter in the list, the 
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parameter must point to a halfword of binary zeros. ; 

If it is the last parameter, it may be omitted. If L j 

omitted, the default page number is 1. Figure 24 on ^ 

page 322 shows the format of the page number area. 

j.Q.li.Sti P . ddr 

specifies the address of a list of externally 
controlled data sets and the addresses of 
corresponding I/O routines. If no external I/O 
routines are supplied, this parameter may be omitted. 

Figure 24 shows the format of the I/O list. 


causes the high-order bit of the last address 
parameter of the PARAM list to be set to 1. 


LOAD AND CALL MACRO INSTRUCTIONS 

Access method services may also be invoked via a LOAD of the 
module IDCAMS, followed by a CALL to that module. The format of 
the LOAD macro instruction is: 


[ name ] 


LOAD 


{EP=IDCAMS | EPLQC= addr . e.ss .at -nams ) 


where: 

EP=IDCAMS 

is the entry point name of the IDCAMS program to be loaded 
into virtual storage. 

EP LOC=a d d r,e £s ....p f,.name 

is the address of an 8-byte character string ’IDCAMS bb*. 

After loading IDCAMS, register 15 must be loaded with the 
address returned from the LOAD macro. Then CALL may be used to 
pass control to IDCAMS. The format of the CALL macro 
instruction is: 



LR 

15.0 

[joam£] 

CALL 

(15). 



(.Qp.tia.pq.d.dr. 



[,dnameaddr] 



C>Panoad_dr] 



Uifllisiaddcl )> 



VL 


where: 

15 

is the register containing the address of the entry point 
to be given control. 

.gpl L o n^ddr . 

specifies the address of an options list that can be 
specified in the PARM parameter of the EXEC statement and 
is a valid set of parameters for the access method services 
PARM command. If you do not want to specify any options, 
this address must point to a halfword of binary zeros. 

Figure 24 on page 322 shows the format of the options list. 

doamaaddc 

specifies the address of a list of alternate dd names for 

standard data sets used during IDCAMS processing. If 

standard ddnames are used and this is not the last ^ 

parameter in the list, it should point to a halfword of 

binary zeros. If it is the last parameter, it may be v 

omitted. Figure 24 shows the format of the alternate 

ddname list. 
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w 



esuaaaddc 

specifies the address of a 6-byte area that contains an 
EBCDIC starting page number for the system output file. If 
the page number is not specified, but this is not the last 
parameter in the list, the parameter must point to a 
halfword of binary zeros. If it is the last parameter, it 
may be omitted. If omitted, the default page number is 1. 
Figure 24 on page 322 shows the format of the page number 
area. 

i o l is . teddr . 

specifies the address of a list of externally controlled 
data sets and the addresses of corresponding I/O routines. 
If no external I/O routines are supplied, this parameter 
may be omitted. Figure 24 shows the format of the I/O 
list. 


causes the high-order bit of the last address parameter in 
the macro expansion to be set to 1. 


INVOCATION FROM A PL/I PROGRAM 

Access method services may also be invoked from a PL/I program 
using the facilities of the IBM PL/I Optimizing Compiler 
Licensed Program. IDCAMS must be declared to the compiler as an 
external entry point with the ASSEMBLER and INTER options. The 
access method services processor is loaded by issuing a FETCH 
IDCAMS statement, is branched to via a CALL statement, and 
deleted via a RELEASE IDCAMS statement. The format of the CALL 
statement is: 


( 


CALL 


IDCAMS 


£ op„ti-Q.ns[, d g a 3 l ,jpaaen.o 3 C,Ipl ls l3); 


where: 

.QRiians 

specifies a valid set of parameters for the access method 
services PARM command. If no parameters are to be 
specified, options should be a halfword of binary zeros. 
Figure 24 on page 322 shows the format of the options area. 

. d n.a m . es 

specifies a list of alternate ddnames for standard data 
sets used during IDCAMS processing. If standard ddnames 
are used and this is not the last parameter in the list, 
dnames should be a halfword of binary zeros. If it is the 
last parameter, it may be omitted. Figure 24 shows the 
format of the alternate ddnames list. 


P-aaejiQ. 

specifies a 6-byte field that contains an EBCDIC starting 
page number for the system output file. If the page number 
is not specified, but this is not the last parameter in the 
list, the parameter must be a halfword of binary zeros. If 
it is the last parameter, it may be omitted. If not 
specified, the default page number is 1. Figure 24 shows 
the format of the page number area. 


specifies a list of externally controlled data sets and the 
addresses of corresponding I/O routines. If no external 
I/O routines are supplied, this parameter may be omitted. 
Figure 24 shows the format of the I/O list. 
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OPTIONS LIST 


LENGTH 



* * - 1 

OPTIONS I 


OPTIONS LIST: Required. Provides a 
way to specify processing options. If 
you do not wish to specify any options, 
you must set the LENGTH field to 
binary zeros. 

LENGTH: Halfword that specifies the 
number of bytes in the OPTIONS field. 

OPTIONS: Character string that con¬ 
tains the processing options of the access 
method services PARM command. The 
options may be specified in the PARM 
field of the EXEC statement or they may 
be set up by the problem program. The 
options must comply with the parameter 
syntax of the access method services 
PARM command. 


DDNAME, 


IOROUT1NE 


USER DATA, 


t 


DDNAME- 


INPUT/OUTPUT LIST: Optional. Provides the means of 
identifying those data sets for which the invoker wishes to 
manage all I/O operations. 

n: A full word that specifies the number of groups of three 
fields that follows. Each group consists of a DDNAME address, 
an IOROUTINE address, and a USER DATA address. 

DDNAME: Address of a character string that identifies a 
data set that will result in the invocation of the associated 
IOROUTINE for all I/O operations (including OPEN and 
CLOSE) against the data set. The character string identifies 
the data set as either a 10-byte or 46-byte character string 
as follows: 

A 10-byte character string: The first two characters are ‘DD’, 
^ the next 8 characters are the DDNAME field value 

left-justified (padded with blanks if necessary), which may 
appear in the FILE, INFILE, or OUTFILE parameters of any 
access method services command. The SYSIN and 
SYSPRINT ddnames may also appear if the invoker wishes 
to manage these data sets. 


binary zeros 
(8 bytes) 


binary zeros 
(8 bytes) 


binary zeros 
( 8 bytes ) 


SYSINtttt) 


SYSPRINT 


f !OROUTINE n 


t 


USER DATA n 


A 46-byte character string: The first two characters are 
‘DS’, the next 44 characters are the data set name, left- 
justified (padded with blanks if necessary), which may appear 
in the INDATASET, OUTDATASET, or DATASET para¬ 
meters of any access method services command. 

IOROUTINE: Address of the program that is to be invoked 
to process I/O operations upon the data set associated with 
DDNAME. This routine, instead of the processor, will be 
invoked for all operations against the data set. See “User 
I/O Routines” in this appendix for linkage and interface 
conventions between the IOROUTINE and access method 
services. 

USER DATA: Address of a data arda user may use for any purpose. 


DDNAMES LIST: Op¬ 
tional. Provides a way to 
specify alternative names 
for the SYSIN and 
SYSPRINT data sets. 

LENGTH: Halfword that 
specifies the number of 
bytes in the remainder 
of the list. 

DDNAMES: Unseparated 
8-character ddnames, left- 
justified, and padded with 
blanks. To change the 
name of SYSIN or 
SYSPRINT, supply an 
alternate name in the 
same position. If an 
alternate name is not 
supplied, the standard 
name is assumed. If the 
name is not supplied 
with the list, the 8-byte 
entry must contain 
binary zeros. Names in 
any position other than 
those for SYSIN and 
SYSPRINT are ignored. 


Figure 24. Processor Invocation Argument List from a Problem Program 
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Figure 24 on page 322 shows the processor invocation argument 
list as it exists in the user’s area. 

Entry and exit to the access method services processor occurs 
through IDCSA01, a module of the system adapter. Standard 
linkage is used; that is, register 1 points to the argument 
list, register 13 points to a save area, register 14 contains 
the return address, and register 15 contains the entry point 
address for IDCSA01. On exit from the access method services 
processor, register 15 contains the value of MAXCC (see 
"Processor Condition Codes" later in this appendix). 

The argument list, as shown in Figure 24, can be a maximum of 
four fullword addresses pointing to strings of data. The last 
address in the list contains a "1" in the sign field. The first 
three possible strings of data begin with a 2-byte length field. 
A null element in the list can be indicated by either an address 
of zeros or a length of zero. 


PROCESSOR CONDITION CODES 

The processor’s condition code is LASTCC, which can be 
interrogated in the command stream following each functional 
command. The possible values, their meanings, and examples of 
causes are: 

Code Meaning 

0(0) The function was executed successfully. Informational 
messages may have been issued. 

4(4) Some minor problems in executing the complete function 

were encountered, but it was possible to continue. The 
results may not be exactly what the user wants, but no 
permanent harm appears to have been done by continuing. 
A warning message was issued. 

8(8) A function could not perform all that was asked of it. 

The function was completed, but specific details were 
bypassed. 

12(C) The entire function could not be performed. 

16(10) Severe error or problem encountered. Remainder of 
command stream is flushed and processor returns 
condition code 16 to the operating system. 

LASTCC is set by the processor at the completion of each 
functional command. MAXCC, which can also be interrogated in 
the command stream, is the highest value of LASTCC thus far 
encountered. 




User I/O routines enable a user to perform all I/O operations 
for a data set that would normally be handled by the access 
methods services processor. This makes it possible, for 
instance, to control the command input stream by providing an 
I/O routine for SYSIN. As pointed out above, standard linkage is 
used. 

A user I/O routine is invoked by access method services for all 
operations against the selected data sets. The identification 
of the data sets and their associated I/O routines is via the 
input/output list of the processor invocation parameter list 
(see Figure 24 on page 322). 

When writing a user I/O routine, the user must be aware of three 
things: First, the processor handles the user data set as if it 
were a non-VSAM data set that contains variable-length unblocked 
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records (maximum record length is 32760 bytes) with a physical 
sequential organization. The processor does not test for the 
existence of the data set. Second, the user must know the data 
format so that the routine can be coded to handle the correct 
type of input and format the correct type of output. Third, 
each user routine must handle errors encountered for data sets 
it is managing and provide a return code to the processor in 
register 15. The processor uses the return code to determine 
what it is to do next. 

The permissible return codes ares 

Code Meaning 

0(0) Operation successful. 

4(4) End of data for a GET operation. 

8(8) Error encountered during a GET/PUT operation, but 

continue processing. 

12(C) Do not allow any further calls (except CLOSE) to this 
routine. 

Figure 25 on page 325 shows the argument list used in 
communication between the user I/O routine and the access method 
services processor. The user I/O routine is invoked by the 
processor for OPEN, CLOSE, GET, and PUT routines. 

The type of operation to be performed is indicated via IOFLAGS. 
The I0INF0 field indicates, for OPEN and CLOSE operations, the 
data set name or ddname of the data set; for GET and PUT 
operations, the I0INF0 field is used to communicate the record 
length and address. 

A user I/O routine for SYSPRINT receives control each time the 
processor issues a PUT against the SYSPRINT data set. If the 
PUT has been issued to print an IDC message, the unique message 
number is passed to the routine via IOFLAGS (see Figure 25 on 
page 325). Each IDC message is in the form IDCsnnnI or 
IDCsnnnnI, where: 

s is a code indicating the severity of the problem. 

nnn or nnnn is the message number that is unique across all 
IDC messages. 

The 2-byte message number passed via IOFLAGS is the nnn or nnnn 
portion of the message converted to binary. 
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This appendix shows the format of each access method services 
functional command/ parameter abbreviation/ and default. The 
commands are grouped together to allow you to remove these pages 
and use them for a quick reference. 


ALIER=M P BIEY, A ITRX8 TO ^ 


Parameters 

Abbrev. 

ALTER 

— 

£D±CYnamgI/password ] 

— 

IADDVOLUMES(y.pJLsar.[ volser... 1) 1 

AVOL 

[ATTEMPTSt number ) 1 

ATT 

[AUTHORIZATION!entrypoint[ string])1 

AUTH 

[BUFFERSPACECslSS)1 

BUFSP, BUFSPC 

[C0DE[££daJ] 

— 

[CONTROLPWtpassword)] 

CTLPW 

[ DESTAGEWAIT | NODESTAGEWAIT1 

DSTGW NDSTGW 

[ EMPTYINOEMPTY] 

EMP NEMP 

[ERASE I NOERASE] 

ERAS NERAS 

[ EXCEPTIONEXIT(gatCYRQ-Lni ) l 

EEXT 

[FILEC ddname ) ] 

— 

[ FREESPACE (CIn & er.QQ,n.t[ CA-percentl ) 1 

FSPC 

[INHIBIT|UNINHIBIT] 

INH UNINH 

[KEYS[leggtb offset)] 

— 

[MASTERPwtEassnand)1 

MRPW 

[NEHNAHE ( newname )] 

NEWNM 

[NULLIFYf 

NULL 

[AUTHORIZATION ( MODULE | STRING )] 

AUTH MDLE 

STRG 

[CODE] 

— 

[CONTROLPW] 

CTLPW 

[EXCEPTIONEXIT] 

EEXT 

[MASTERPWI 

MRPW 

[OWNER] 

— 

[READPW] 

RDPW 

[RETENTION] 

RETN 

[UPDATEPW1 )] 

UPDPW 

[ owner ( gwnaci-d ) ] 

— 

C READPW ( password )] 

RDPW 

[ recordsize ( average maximum)] 

RECSZ 

[REMOVEVOLUMESCvolser [ volser. ..]1] 

RVOL 

[SCRATCH | NOSCRATCH] 

SCR NSCR 

[SHAREOPTlONSCcrgsacsaianl aaesssYsiam] )] 

SHR 

[STAGEiBIND ICYLINDERFAULT] 

- CYLF 

[TOCjdaia) iFOR(days)] 

— 

[UNIQUEKEY|NONUNIQUEKEY] 

UNQK NUNQK 

[UPDATE|NOUPDATE] 

UPD NUPD 

[UPDATEPW C pa sswo rd)] 

UPDPW 

[UPGRADEI NOUPGRADE] 

UPG NUPG 

[WRITECHECKINOWRITECHECK] 

WCK NWCK 

[CATALOGlsainamet/pasawand] )1 

CAT 
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Parameters 

Abbrev. 

BLDINDEX 

BIX 

CINFILE(ddnamet/password]JI 

IFILE 

INDATASET (.ant cyna m e I /password ]) 3 

IDS 

{QUTFlLEEddnamoE/password! 

OFILE 

C J)| 


OUTDATAS ETEentrynameE/password1 

ODS 

E entrvnameE/passwordl...1)3 


ECATALOGEcatnameE/passwordl)1 

CAT 

E EXTERNALSORT | JtLT.ERNAUS.QRI] 

ESORT ISORT 

EWORKFlLESEsisip.ams ddnaiiLe)] 

NFILE 


CHKLIST—IDENTIFY TAPE VOLUMES MOUNTED WHEN A CHECKPOINT WAS TAKEN 


Parameters 

Abbrev. 

CHKLIST 

CKLST 

INFILEtd-dnaros) 

IFILE 

ECHECKiDirhspkid.•.)] 

CHKID 

[OUTFXLEEddname)] 

OFILE 


mVXCj^T—^QijVgR3LJ^_C^PJ^ g NJ.RI-ES- I N TO V S A M C ATALOG E NT RIES 


Parameters 

Abbrev. 

CNVTCAT 

CNVTC 

{INFILEEddnameE/password!11 

IFILE 

E INDATASET(entrvnameE/passwordl)3 

IDS 

{OUTFI LEC.ddnamqE /password 1J 

OFILE 

E OUTDATASETEentrvnameE/passwordl)3 

ODS 

CCATALOG(catnameC/passwordJ)2 

CAT 

ECVOLEQUATESC(catname (volser 

CVEQU 

t volser...2))[ Ccatname.222 


ELIST|NOLISTl 

— NLIST 

EMASTERCATALOGtcatname[/password2 2 2 

MCAT 
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Parameters 


Abbrev. 



Parameters 


Abbrev. 


DEFINE ALTERNATEINDEX 


DEF AIX 


{CYLINDERS 1 (acAjnacy! 
RECORDS 1 ( primary ! j 
TRACKS 1 ( primary ! Si 
VOLUMES 2 ( volser ! vol 
(ATTEMPTS! number 12)1 


IBUFFERSPACE( size )2 
(CODE(cade)2 

(CONTROLINTERVALSIZE( size )2 
[CQNTROLPW( password )2 
(DESTAGEWAITI N0DESTAGEWAIT 2 
(ERASElMSEBASf) 


(FILE! ddname )2 
(FREESPACE! Cl-perce 
(IMBEDI NOIMBED 2 
(KEYRANGES(( Low k.ey 


s±nina2)2 


(KEYS (lansih 


:)...))) 

PJ2 


IP P) 


REL 

CYL 

REC 

TRK 

VOL 

ATT 

AUTH 

BUFSP, BUFSPC 

CISZ, CNVSZ 
CTLPW 

DSTGW NDSTGW 
ERAS NERAS 
EEXT 

FSPC 

IMBD NIMBD 
KRNG 


[ORDERED| 


ORD UNORD 


MSP 326PP)2 
[REPLICATE I NOREI 
[REUSEI NOREUSE 2 


maximum I 


[ crosssystem )11 3)2 

[SPEED I RECOVERY ) 

[ STAGE | BIND |CYLINDERFAULT2 
[TO(da±a)I FOR(days)2 
[UNIQUE I SUBALLQCATION 2 


[UPDATEPM! password )2 
[ UPGRADE INOUPGRADE2 
[WRITECHECKINOWRITECI 


RDPW 

RECSZ 

REPL NREPL 
RUS NRUS 
SHR 

— RCVY 
-CYLF 

UNQ SUBAL 
UNQK NUNQK 
UPDPW 
UPG NUPG 
HCK NWCK 


(Continued; notes follow) 
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B E EIME,ALIBRNAT UMBE X ...IC gnt inuec}1 


Parameters 

Abbrev. 

[DATA 

— 

([ATTEMPTS!number)] 

ATT 

[AUTHORIZATION!entrvpoint! £± 1 ^])] 

AUTH 

[BUFFERSPACE!size)] 

BUFSP, BUFSPC 

[CODE!code)] 

— 

[CONTROLINTERVALSIZE(size)] 

CISZ, CNVSZ 

[CONTROLPWIpassword)] 

CTLPW 

[CYLINDERS(primary! secondary])1 

CYL 

RECORDS!primary! secondary])1 

REC 

TRACKS(primary! Secondary])] 

TRK 

[DESTAGEWAIT1NODESTAGEWAIT1 

DSTGW NDSTGW 

[ERASE|NOERASE] 

ERAS NERAS 

[EXCEPTIONEXIT!entrvpoint) 1 

EEXT 

!FILE(ddname X X)] 

— 

!FREESPACE!CL-percgnt! CA-Percentl)] 

FSPC 

[KEYRANGES!(lowkev hiahkev) 

KRNG 

[(lowkev hjghkey)...])] 


[KEYS!lenath offset)] 

— 

[MASTERPW(oassword)] 

MRPW 

[MODEL(entrvname!/password! 

— 

£ catname£/password33)3 


ENAMECentrvname)3 

— 

[ORDERED|UNORDERED] 

ORD UNORD 

[OWNER!ownerid)] 

— 

EREADPWtpassword)3 

RDPW 

[RECORDSIZE(avernag maximum)] 

RECSZ 

[REUSE I NOREUSE] 

RUS NRUS 

[SHAREOPTIONS!crossregion! nnasssystsm] 

SHR 

[SPEED|RECOVERY] 

— RCVY 

[STAGE|BIND|CYLINDERFAULT] 

-CYLF 

[UNIQUE 1 SUBALLOCATION] 

UNQ SUBAL 

[UNIQUEKEY|NONUNIQUEKEY] 

UNQK NUNQK 

[UPDATEPW!password)] 

UPDPW 

[VOLUMES(volserE volser. ..3)3 

VOL 

[WRITECHECK|NOWRITECHECK])1 

WCK NWCK 


(Continued; notes follow) 
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Parameters 

Abbrev. 

[INDEX 

IX 

([ATTEMPTS(number)] 

ATT 

[AUTHORIZATION(entrypoint[ string))) 

AUTH 

[CODEC code)] 

— 

[CONTROLINTERVALSIZEtsizel1 

CISZ, CNVSZ 

ECONTROLPWEpassword)3 

CTLPW 

[CYLINDERS(prim3ryt seqpndarvl)1 

CYL 

RECORDS(primarv[ secondary))1 

REC 

TRACKSCprimarvE secondarv3)T 

TRK 

[DESTAGEWAIT|NODESTAGEWAIT) 

DSTGW NDSTGW 

[ except I0NEXIT( entrypoio-t)) 

EEXT 

[PILE(ddname)] 

— 

[IMBEDINOIMBED) 

IMBD NIMBD 

[MASTERPWCpassword)] 

MRPW 

[MODELCentryname[/password] 

— 

[ catnameC/password)))) 


ENAME(entrvname)3 

— 

[ORDERED!UNORDERED] 

ORD UNORD 

[QWNERtpMoeridn 

— 

t READPW(password)3 

RDPW 

[REPLICATE 1NOREPLICATE1 

REPL NREPL 

[REUSE!NOREUSE] 

RUS NRUS 

E SHAREOPTIONS(crossreaion E crosssvstem3)3 

SHR 

[STAGE I BIND|CYLINDERFAULT] 

-CYLF 

[UNIQUE|SUBALLOCATION] 

UNQ SUBAL 

[UPDATEPW(password)] 

UPDPW 

[VOLUMES(volser[ volser...])] 

VOL 

[WRITECHECK|NOWRITECHECK])] 

WCK NMCK 

[CATALOG(catnameC/password1)] 

CAT 


Notes 

1 CYLINDERS, RECORDS, or TRACKS must be specified either as a 
parameter of ALTERNATEINDEX, as a parameter of DATA, or as a 
parameter of both DATA and INDEX if MODEL is not specified. 

2 VOLUMES must be specified as a parameter of ALTERNATEINDEX 
or as a parameter of both DATA and INDEX if MODEL is not 
specified. 
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Parameters 

Abbrev. 

DEFINE CLUSTER 

'DEF CL 

C NAME(&n±EYDama) 

— 

{CYLINDERS 1 (primary! secondary!) 1 

CYL 

records 1 Cpximsryt s.espndaryJ)1 

REC 

TRACKS 1 C primarvE secondary])T 

TRK 

VOLUMES 2 (voigerC volser.♦. 3 3 

VOL 

[ATTEMPTS!number 1233 

ATT 

[AUTHORIZATION!entrvpoint[ strina333 

AUTH 

[BUFFERSPACECsize 3] 

BUFSP, BUFSPC 

[CODEC code3] 

— 

ICONTROLINTERVALSIZEtsize11 

CISZ, CNVSZ 

[CONTROLPW!password)3 

CTLPW 

[DESTAGEWAIT1N0DESTAGEWAIT3 

DSTGW NDSTGH 

[ERASE 1N0ERASE1 

ERAS NERAS 

[EXCEPTIONEXIT(entrvpoint]] 

EEXT 

[FILEC ddname)] 

— 

[FREESPACE 3 !Cl-percent 

FSPC 

[ CA-percent3 Ifl j&)3 


[IMBEDINQJMBED3 3 

IMBD NIMBD 

[INDEXED 1NONINDEXEDI NUMBERED 3 

IXD NIXD NUMD 

IKEYRANGES 3 ((lowkev highkev) 

KRNG 

[[lowkey hjghkey!...3)3 


[KEYS 3 (length offset IM £33 

— 

[MASTERPW(password 3 3 

MRPN 

[MODEL(entrvname[/password3 

— 

E catnameC/password]])] 


[ORDERED 1UNORDERED 3 

ORD UNORD 

[OWNER!ownerid3 3 

— 

E READPW C passwo rd)] 

RDPW 

[RECORDSIZE*(average maximum 33 

RECSZ 


REPL NREPL 

[REUSE I NOREUSE3 

RUS NRUS 

[SHAREOPTIONS(crossreaion 

SHR 

[ crosssystem3|1 333 


[SPANNED 1NONSPANNED3 

SPND NSPND 

[SPEED 1 RECOVERY] 

— RCVY 

[STAGEiBIND 1CYLINDERFAULT3 

-CYLF 

[TO(date 3IFOR(davs33 

— — 

[UNIQUE ISUMU0CM10M3 

UNQ SUBAL 

[UPDATEPW(password 3 3 

UPDPW 

[WRITECHECK1NOWRITECHECK]3 

WCK NWCK 


(Continued; notes follow) 
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E JE-EXHE _QUJ^XElB _LCaLQ^J.iiyjedJ. 


Parameters 

Abbrev. 

[DATA 

— 

C[ATTEMPTS!number)] 

ATT 

[AUTHORIZATION (sn±nyEflijD±[ siring])] 

AUTH 

[BUFFERSPACE(size)] 

BUFSP, BUFSPC 

[CODE!code)3 

— 

[CONTROLINTERVALSIZE!sizen 

CISZ, CNVSZ 

[CONTROLPWIPassword)] 

CTLPW 

ECYLINDERSEprimaryE secondary3)1 

CYL 

RECORDSIErimaryC secondary])1 

REC 

TRACKS!REimary[ secondary])] 

TRK 

[DESTAGEWAIT|NODESTAGEWAIT] 

DSTGW NDSTGW 

[ERASE|NOERASE] 

ERAS NERAS 

[EXCEPTIONEXIT!entrvpoint)] 

EEXT 

[FILEiddname)] 

— 

[FREESPACE 3 !clzBftcgfloiE CA-psrgent])] 

FSPC 

[KEYRANGES 3 !!lowkev hiahkev) 

KRNG 

! !lowRey Mahkey )..♦])] 


[KEYS 3 [length offset)] 

— 

[MASTERPW!password)] 

MRPW 

[MODEL!entrvname!/password] 

— 

[ cafriame!/password 1 ]) ] 


[NAME!entrvname)I 

— 

[ORDERED|UNORDERED] 

ORD UNORD 

[OWNER!ownerid)] 

— 

EREADPWCpassword)3 

RDPW 

[RECORDSIZE(average maximum)] 

RECSZ 

[REUSE I NOREUSE] 

RUS NRUS 

[SHAREOPTiONS!crpssregion[ srosssystem])] 

SHR 

[SPANNED|NONSPANNED1 

SPND NSPND 

[SPEED!RECOVERY] 

— RCVY 

[STAGE|BIND|CYLINDERFAULT] 

-CYLF 

[UNIQUE!SUBALLOCATION] 

UNQ SUBAL 

EUPDATEPWEpassword)3 

UPDPW 

EVOLUMESfvolserE volser...3)3 

VOL 

[WRITECHECKINOWRITECHECK])] 

WCK NWCK 


(Continued; notes follow) 
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REJELUjJS_C L USJ JE R-^Jj£gD±JUlMe^iJL 


Parameters 

Abbrev. 

[INDEX 3 

IX 

(CATTEHPTSCnumber)I 

ATT 

[ AUTHORIZATION (entrypointt siriusD) 

AUTH 

[CODEC code)1 

— 

[CONTROLINTERVALSIZE(siZ£)1 

CISZ,CNVSZ 

[CONTROLPWCPassword)] 

CTLPW 

[CYLINDERS(primary[ secondary])| 

CYL 

RECORDSCprimary[ secondary])1 

REC 

TRACKSCorimarv[ secondary])] 

TRK 

[DESTAGEWAIT1NODESTAGEWAIT] 

DSTGW NDSTGW 

[EXCEPTIONEXITtentrvpoint)1 

EEXT 

CFILE(ddname)] 

— 

[IMBED|NOIMBED] 3 

IMBD NIMBD 

[MASTERPWtpassword)] 

MRPW 

£MODELCentrvname[/password3 

— 

[ catname[/password)])] 


[NAME(entryname)1 

— 

[ORDERED|UNORDERED] 

ORD UNORD 

[OWNERCownerid)] 

— 

EREADPWCpassword)3 

RDPW 

[REPLICATE|NOREPLICATE] 3 

REPL NREPL 

[REUSE|NOREUSE] 

RUS NRUS 

[SHAREOPTIONSt ctPSSregjpn[ crosssvstem] ) 1 

SHR 

[STAGE!BIND ICYLINDERFAULT] 

-CYLF 

[UNIQUE!SUBALLOCATION] 

UNQ SUBAL 

[UPDATEPWC password)] 

UPDPW 

EVOLUMESCvolser[ volser.*.3)3 

VOL 

[WRITECHECK|N0WRITECHECK1)] 

WCK NWCK 

[CATALOG(catnamel/cassword])] 

CAT 


Notes 

1 CYLINDERS^ RECORDS, or TRACKS must be specified either as a 
parameter of CLUSTER, as a parameter of DATA, or as a 
parameter of both DATA and INDEX if MODEL is not specified. 

2 VOLUMES must be specified as a parameter of CLUSTER or as a 
parameter of both DATA and INDEX if MODEL is not specified. 

3 Can only be specified for a key-sequenced cluster. 

4 When SPANNED is specified, the default is RECORDSIZE 
C 4086 32800 ). Otherwise, the default is RECORDSIZE 
CM 82 M 82 ) . 
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Parameters 


DEFINE GENERATIONDATAGROUP 


LIMIT 

IEMPTY NOEMPTY ] 


ISCRATCH I NOSCRATCH I 
[TOC date )IFORt days )3) 


Abbrev. 


DEF GDG 
LIM 

EMP NEMP 
SCR NSCR 

CAT 


Parameters 


DEFINE NONVSAM 


VOLUMES( yolse xl volser ... 3 ) 
I FILESEQUENCENUMBERSt number 
[ number ...333 
[QWNERC ownerid )3 
ETO( date )iFORC davs )!) 


Abbrev. 


DEF NVSAM 

DEVT 

VOL 

FSEQN 


Parameters 

Abbrev. 

DEFINE PAGESPACE 

DEF PGSPC 

l name, l ent rynanie. J 
tCYLINDERS( primary)1 

CYL 

RECORDS(primary)| 

REC 

TRACKS(primary)3 

TRK 

VOLUME(volser) 

VOL 

[ATTEMPTS(number 12)1 

ATT 

[AUTHORIZATION(entrypointl string) ) 3 

AUTH 

(CODE(code)l 

— 

[CONTROLPW(password)1 

CTLPW 

CFILE(ddname)1 

— 

[MASTERPW(password)1 

MRPW 

[MODEL C eatryname l /password 3 
[ catnameE/password31)1 

IOWNER(ownerid) 1 
[READPW(password)1 


RDPW 

[SWAP 1NOSWAP3 

— NSWAP 

[TO(date)1FOR(days)3 

— 

[UNIQUE 1 SUBALLOCATION1 

UNQ SU6AL 

[UPDATEPW(password)3) 

UPDPW 

[ CATALOG (ca t name i /pas^wpr c) 1)1 

CAT 
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DEFINE PATH—DEFINE A RELATIONSHIP BETWEEN AN ALTERNATE INDEX AND ITS BASE CLUSTER 


Parameters 

Abbrev. 

DEFINE PATH 

DEF — 

(NAME(entrvname) 

— 

PATHENTRYCentryngmfit/Rgsswprdl) 

PENT 

[ATTEMPTS( number 12)1 

ATT 

E AUTHORIZATION ervtrypointE strinal)3 

AUTH 

[CODEC code)] 

— 

[CONTROLPWCpassword)] 

CTLPW 

EFILECcfdpame) 3 

— 

[MASTERPWCpassword)3 

MRPW 

[MODELCentrynameC/passwordI 

— 

[ catname[/password31)3 

COWNER(ownerid)3 

_ 

[READPWCpassword3 3 

RDPW 

[TOCdate]IFORCdavs)3 

— — 

[UPDATE 1 NOUPDATE3 

UPD NUPD 

EUPDATEPWCpassword 3 33 

UPDPW 

[CATALOGCcaioame[/password3 3 3 

CAT 


M£IME^J\£5z=S£FJJjE_&JLSA)LBATA-S.£A C £._ i:i i_A.,.V_S AM _P4T AL OG 


Parameters 

Abbrev. 

DEFINE SPACE 

DEF SPC 

({CANDIDATE| 

CAN 

CYLINDERS(primarv[ secondary3)1 

CYL 

RECORDSCprimery[ secondary3) 

REC 

RECORDSIZE(average maximum)| 

RECSZ 

T RAC KS(prima r y[ secondary33J 

TRK 

VGLUMESEvolserE volser...3) 

VOL 

[FILEC ddname)3 3 

— 

ECATAL0GCcatnameE/password3 3 3 

CAT 
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Parameters 

Abbrev. 

DEFINE USERCATALOG|MASTERCATALOG 

DEF UCAT MCAT 

!NAME!entryname) 

— 

{CYLINDERS(enimanyt secondary])1 

CYL 

RECORDS(p rima rv C secondary])| 

REC 

TRACKStprimary! secondary])} 

TRK 

VOLUMEIvaLser) 

VOL 

[ATTEMPTS!number 121] 

ATT 

[AUTHORIZATIONt.antCYBQ.irLtI siring] )] 

AUTH 

[BUFFERSPACEIsize13072)] 

BUFSP, BUFSPC 

[CODEtcode)] 

— 

ICONTROLPWCpassword)] 

CTLPW 

[ DESTAGEWAIT | NODISIMIWMI1 

DSTGW NDSTGW 

[FILE!ddname}] 

— 

[MASTERPWtpassword)] 

MRPW 

[MODEL(entryname[/password] 

— 

[ caloams[/password]])1 


[OWNER!ownerid)] 

— 

C READPWC password)3 

RDPW 

[RECORDSIZE(averqae maximum)3 

RECSZ 

[RECOVERABLE INQTRECOVERAgLE] 

RVBL NRVBL 

[TO!date)IFOR!davs)] 

— — 

[UPDATEPW!password)I 

UPDPW 

[WRITECHECK |M8MRIIE£ttS£K]) 

WCK NWCK 

[DATA 

— 

! [BUFFERSPACE!size)l 

BUFSP, BUFSPC 

[CYLINDERS!primary! secondary])1 

CYL 

RECORDS[primary! secondary])1 

REC 

TRACKSIprimary! secondary])] 

TRK 

[DESTAGEWAITINODESTAGEWAITl 

DSTGW NDSTGW 

[RECORDSIZE!average maximum)1 

RECSZ 

[RECOVERABLEINOTRECOVERABLE] 

RVBL NRVBL 

[WRITECHECK1NOWRITECHECK])] 

WCK NWCK 

[INDEX 

IX 

I[CYLINDERS!prima rv)1 

CYL 

RECORDS[primarv)1 

REC 

TRACKS!primary)] 

TRK 

[DESTAGEWAITINODESTAGEWAITl 

DSTGW NDSTGW 

[WRITECHECK|NOWRITECHECK])] 

WCK NWCK 

[ CATALOG ! mas±e.cp.alnaiafi ! /password ]) 1 

CAT 


Vi- 
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Parameters 

Abbrev. 

DELETE 

DEL 

(entry-name [/password! 

— 

[ entrynamet/passwordl.. ♦ I ) 

[ALIAS| 


ALTERNATEINDEXI 

AIX 

CLUSTER I 

CL 

GENERATIONDATAGROUP| 

GDG 

NONVSAM| 

NVSAM 

PAGESPACE| 

PGSPC 

PATHI 

— 

SPACE 1 ! 

SPC 

USERCATALOG 1 

UCAT 

[ERASE 1 NOERASE 1 

ERAS NERAS 

[FILE(ddname)3 

— 

[FORCE1 NOFORCE1 

FRC NFRC 

IPURGE 1 NOPURGE] 

PRG NPRG 

ISCRATCH 1 NOSCRATCH] 

SCR NSCR 

[ cat alog (gaAnamfl I /passana nd 11 3 

CAT 


Notes 

1 When you delete a data space or catalog, you cannot delete 
any other type of entry. You must identify the type of 
entry to be deleted, by specifying SPACE or USERCATALOG. 
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Parameters 


EXPORTRA 

OUTFILE( ddname ) 

CRA( 


CALL! INFILE( ddname 2)3I 
ENTRIES( 

CenicynamsC ddname5 3) 

[( entrvname l ddname5 3)< 
NONE}) 

IC ddnamel •••]«•»]) 

IFORCEl NPEflBCfi l 
CMASTERPW(password)3 


Abbrev. 


XPRA 

OFILE 


IFILE 


FRC NFRC 
MRPW 


5QT A USER CATAIPQ 


Parameters 

Abbrev. 

IMPORT 

IMP 

CONNECT 

CON 

OBJECTS((usercatname 

OBJ 

DEVICETYPE[devtvoe) 

DEVT 

VOLUMEStvolser))) 

VOL 

[ CATALOG ( mas t.acaatnam@ t /passw.or.d 3) 3 

CAT 


H y I U«J NyiiPN WiMEia y I 


Parameters 


Abbrev. 


IMPORT 

£INFILEf ddname l|INDATASETC 
£OUTFILE{.dd.o a .me.['' P . as .s. wor ,d3) I 
OUTDATASET( entrvname [/ passw 
[ERASE|NOERASE3 
[INTOEMPTY3 
[OBJECTS(t entrvname 
EFILEt d .dnam e .n 
[KEYRANGESC C lpwR e y highl y) 
[ (iowRey hiah&gy 3... 3) 3 
[NEWNAME(nsHnamfiJ3 
[ORDERED IUNORDERED3 
t [ VOLUMES(yo l a ac[ ^ volser ... 

[PURGE I NOPURGE 3 * 

[SAVRACINOSAVRAC 3 




...3)3) 


IMP 

IFILE IDS 

OFILE 

ODS 

ERAS NERAS 
IEMPTY 
OBJ 


NENNM 
ORD UNORD 
VOL 

PRG NPRG 


/f ^ 

i ” 
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IMBQRIR&r R ES TORE CATAL Q6.ENI BI . ES .E KOM -AJEflRI A Rt. E - PA T A . aEUgREATE P - B Y- IH E EX P PR T RA 

COMMAND FOR VSAM RECOVERABLE CATALOGS 


Parameters 

Abbrev. 

IMPORTRA 

MPRA 

CINFILECddnams)1INDATASET!entrvname)! 

IFILE IDS 

[QUTFILE!ddname)3 

OFILE 

[OBJECTSC 

OBJ 

(ejoicxname 


IDEVICETYPESCdevtvpet devtvpe...3)3 

DEVT 

CFILE(ddname)] 

— 

[VOLUMES(volserl volser.♦.3)3) 

VOL 

Kentryname...)... 3)3 


[ SAVRAC | MQSMRAC 3 

— — — 

[ CAT ALOG (.oatname t /Easawecd 1) 3 

CAT 


LI5I£ A I ==L I S 1_EMIR 1£§ . FROM . A.CATALOG 


Parameters 

Abbrev. 

LISTCAT 

LISTC 


ENT 

LEVEL!level)3 

LVL 

[ALIAS] 

— 

[ ALTERNATEINDEX3 

AIX 

[ CLUSTER3 

CL 

[ DATA) 

— 

[ GENERATIONDATAGROUP3 

GDG 

[ INDEX) 

IX 

[ NONVSAM) 

NVSAM 

[ PAGESPACE) 

PGSPC 

[ PATH) 

— 

[ SPACE) 

SPC 

I USERCATALOG3 

UCAT 

[CREATION!davs)3 

GREAT 

[EXPIRATION!davs)3 

EXPIR 

[NAME 1 

— 

HISTORYI 

HIST 

VOLUME| 

VOL 

ALLOCATION! 

ALLOC 

ALL) 

— 

[NOTUSABLE3 

NUS 

[OUTFILE!ddname)3 

OFILE 

[CATALOGIcatnamg[ /password 3 ) 3 

CAT 


LISTCRA—LIST THE CONTENTS OF THE CATALOG RECOVERY AREA ICRA) FOR VSAM RECOVERABLE 

CAIALQCS 


Parameters 

Abbrev. 

LISTCRA 

lNFlLE!.ddnamfi[ ddname* ♦ • 1) 

[ catalog ! .cat name [ /password I ddname) 3 
[ COMPARE IN.QCQMP.ARE 3 
[DUMP I NAME 1SEQUENTIALDUMP3 
[MASTERPWIpassword)3 
[OUTFILE!ddname)! 

LISTR 

IFILE 

CAT 

CMPR NCMPR 

- SDUMP 

MRPW 

OFILE 
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Emm:=egi H Tjn « ^ 


Parameters 

Abbrev. 

PRINT 

CINFILEtddnamet/password!)I 

INDATASET(entrynameE/password3 IT 
[OUTFlLECddname)] 

£ CHARACTER|PUMP 1 HEX] 

EFROMKEY(key)J FROMADDRESSCaddcsssl1 

FROMNUMBERInumber)1SKIP!count)] 
ETOKEY(kev)lTOADDRESS(address)1 

TONUMBERC number)|COUNT!count)] 

IFILE 

IDS 

OFILE 

CHAR- 

FKEY FADDR 

FNUM — 

— TADDR 

TNUM — 


R EE Bfl=£ a^^ . 

catalogs and split or merge integrated catalog facility catalogs 


Parameters 

Abbrev. 

REPRO 

— 

{INFILE (ddaams £ /p.aggw.Q.rd ] 

IFILE 

E ENVIRONMENT(DUMMY)1)| 

ENV BUM 

INDATASETC entpvnameE/passwordl 

IDS 

E ENVIRONMENTlDUMMY)])J 

ENV DUM 

COUTFILEEddnameE/passwordI)| 

OFILE 

OUTDATASET(fip_tr.yp.amg.E /piaagligJld] )} 

ODS 

EDECIPHER 

DECPHR 

(CDATAKEYFILE(ddname) | 

DKFILE 

DATAKEYVALUE t va1ue)1SYSTEMKEY] 

DKV SYSKEY 

E SYSTEMDATAKEY(value)] 

SYSDK 

[SYSTEMKEYNAME(kevname)])] 

SYSKN 

EENCIPHER 

ENCPHR 

(C EXTERNALKEYNAME(k evname)1 

EKN 

INTERNALKEYNAMEtkevname)IPRIVATEKEY^ 

IKN PRIKEY 

ECIPHERUNITtnumber 11)1 

CPHRUN 

EDATAKEYFILE(ddname)1DATAKEYVALUE(value)] 

DKFILE DKV 

ESHIPKEYNAMES(keynameE keyname... ] ) ] 

SHIPKN 

[STOREDATAKEY1NOSTOREDATAKEY] 

STRDK NSTRDK 

C STOREKEYNAME(kevname)] 

STRKN 

[USERDATAlvalue)])] 

UDATA 

EFROMKEY(key)|FROMADDRESS(addCfiSS)1 

FKEY FADDR 

FROMNUMBER(number)1 SKIP!count)! 

FNUM — 

EREPLACE 1N0REPLACE1 

REP NREP 

E REUSEINflRIUSIl 

RUS NRUS 

ETOKEY(kev)1TOADDRESSEaddress)1 

— TADDR 

T0NUMBER(number)|COUNT(count)] 

TNUM — 


Notes: The ENCIPHER and DECIPHER parameters apply only with the 
Programmed Cryptographic Facility (5740-XY5) or the IBM 
Cryptographic Unit Support (5740-XY6). (For more information, 
see yjS. M ..A dm^ - ) 


4 "s 
(3 
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RESETCAT—SYNCHRONIZE A VSAM RECOVERABLE CATALOG TO TH E LEVEL OF ITS OWNED VOLUMES 


Parameters 

Abbrev. 

RESETCAT 

RCAT 

CATALOG(catname[/passwordIt ddnaroe]) 
fCRAFILESf(ddnamel[ ALLI NONE!) 

CAT 

[[ddnamel[ ALLI NONE])...Ill 

- - 

CRAVOLUMESlCvolsert devtvoe]) 

CRAVOL 

[Cvolser[ devtvpel)...])} 


[IGNOREINOIGNOREJ 

IGN NIGN 

[MASTERPWt password)1 

MRPW 

[WORKCAT(catname[/password])] 

WCAT 

CWORKFILEtddnameE/password])3 

WFILE 


VEB I F-Y—R EST O RE . A . VgA tLCU/aiE RLSL g M B-gE=E lL i_J &mg3 


Parameters 

Abbrev. 

VERIFY 

VFY 

{FILEC ddname[/password))1 

— 

DATASET (entryname[/password3)J 

DS 
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EXECUTION CONTROL COMMANDS 


IF-THEN-ELSE COMMAND SEQUENCE 


Parameters 


IF 

£ lastcc | maxccj cgmEacaiid number 

THENE command 1 

DO 

command set 

END] 

EELSEE command 1 

DO 

comjnaod ss± 

END]] 



PARM COMMAND 


Parameters 


PARM 

ETESTE 
£ETRACE] 

Eareas( aneaidE araaid...])1 

EFULLE(dumpidE countlE count211) 

[Cdumnid. **)...])] 1 

OFF})] 

EGRAPHICSECHAINEchain) ITABLEEroname))] 

E margins E JLefima csin riahimarain) ] 



SET COMMAND 


Parameters 


SET 

{MAXCC!LASTCC} = number 
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GLOSSARY 


The following terms are defined as they 
are used in this book. If you do not 
find the term you are looking for, see 
the index or the ,1 BM ,.. Di .C±i Q nar y ... pf 
fiafflRM t iLP fl j. SC20-1699. 

access method services. A multifunction 
service program that defines VSAM data 
sets and allocates space for them, 
converts indexed-sequential data sets to 
key-sequenced data sets with indexes, 
modifies data-set attributes in the 
catalog, reorganizes data sets, 
facilitates data portability between 
operating systems, creates backup copies 
of data sets and indexes, helps make 
inaccessible data sets accessible, and 
lists the records of data sets and 
catalogs. 

alias. An alternative name for an 
entry. 

alias entry. An entry that relates an 
alias (alternate entryname) to the real 
entry name of a user catalog or non-VSAM 
data set. 

alternate-index entry. A catalog entry 
that contains information about an 
alternate index. An alternate index is 
conceptually a key-sequenced cluster, 
and is cataloged in the same way. An 
alternate-index entry points to a data 
entry and an index entry to describe the 
alternate-index’s components, and to a 
cluster entry to identify the 
alternate-index’s base cluster. ( See 
also cluster entry.) 

alternate-index record. A collection of 
items used to sequence and locate one or 
more data records in a base cluster. 

Each alternate-index record contains an 
alternate-key value and one or more 
pointers. When the alternate index 
supports a key-sequenced data set, each 
data record’s prime key value is the 
pointer. When the alternate index 
supports an entry-sequenced data set, 
the data record’s RBA value is the 
pointer. ( See also alternate-index 
entry, alternate key, base cluster, and 
key. ) 

alternate key. One or more characters 
within a data record, used to identify 
the data record or control its use. 
Unlike the prime key, the alternate key 
can identify more than one data record. 
(S&£_al££ key and key field.) 

application. As used in this 
publication, the use to which an access 
method is put or the end result that it 
serves; contrasted to the internal 
operation of the access method. 


backup data set. A copy that can be 
used to replace or reconstruct a damaged 
data set. 

base cluster. The VSAM cluster whose 
data records are to be accessed through 
a path. Usually, a base cluster is the 
key-sequenced or entry-sequenced data 
set which an alternate index supports 
(that is, an alternate index is used by 
VSAM to sequence and locate the data 
records of a base cluster). ( See also 
alternate-index entry and path.) 

catalog. ( See master catalog and user 
catalog.) 

catalog cleanup. A process that allows 
the deletion of entries if their volume 
is no longer available; catalog cleanup 
also allows deletion of a catalog even 
though it is not empty. Catalog cleanup 
is a function of the DELETE command. 

catalog connector. A catalog entry, 
called either a user catalog entry or a 
catalog connector entry, in the master 
catalog that points to a user catalog’s 
volume (that is, it contains the volume 
serial number of the direct-access 
volume that contains the user catalog). 

catalog recovery area. An 
entry-sequenced data set that exists on 
each volume owned by a recoverable 
catalog, including the volume on which 
the catalog resides. The CRA contains 
copies of the catalog’s records, and can 
be used to recover a damaged catalog. 

cell. An occurrence of information such 
as passwords, volume information, or 
associations. 

cluster. A data component and an index 
component when data is key sequenced; a 
data component alone when data is entry 
sequenced. 

cluster entry. A catalog entry that 
contains information about a 
key-sequenced or entry-sequenced VSAM 
clusters ownership, cluster attributes, 
and the cluster’s passwords and 
protection attributes. A key-sequenced 
cluster entry points to a data entry and 
an index entry. An entry-sequenced 
cluster entry points to a data entry. 

component. The data portion or, for a 
key-sequenced cluster, alternate index, 
or VSAM catalog, the index portion of a 
VSAM object. In this book, the 
components of an object are usually 
referred to as the object’s data 
component and index component. Also, 
the cluster, data, or index fields of a 
subrecord. 
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control area. A group of control 
intervals used as a unit for formatting 
a data set before adding records to it. 
Also, in a key-sequenced data set, the 
set of control intervals pointed to by a 
sequence-set index record; used by VSAM 
for distributing free space and for 
placing a sequence-set index record 
adjacent to its data. 

control interval. A fixed-length area 
of auxiliary-storage space in which VSAM 
stores records and distributes free 
space. It is the unit of information 
transmitted to or from auxiliary storage 
by VSAM. 

CRA. ( See catalog recovery area.) 

data component. That part of a VSAM 
data set, alternate index, or catalog 
that contains the object’s data records. 

data entry. A catalog entry that 
describes the data component of a 
cluster, alternate index, page spaces, 
or catalog. A data entry contains the 
data component's attributes, allocation 
and extent information, and statistics. 

A data entry for a cluster’s or 
catalog’s data component can also 
contain the data component’s passwords 
and protection attributes. 

data integrity. Preservation of data or 
programs for their intended purpose. As 
used in this publication, the safety of 
data from inadvertent destruction or 
alteration. 

data record. A collection of items of 
information from the standpoint of its 
use in an application, as a user 
supplies it to VSAM for storage. 

data security. Prevention of access to 
or use of data or programs without 
authorization. As used in this 
publication, the safety of data from 
unauthorized use, theft, or purposeful 
destruction. 

data set. The major unit of data 
storage and retrieval in the operating 
system, consisting of data in a 
prescribed arrangement and described by 
control information to which the system 
has access. As used in this 
publication, a collection of fixed- or 
variable-length records in auxiliary 
storage, arranged by VSAM in key 
sequence or in entry sequence. ( See 
also key-sequenced data set and 
entry-sequenced data set.) 

data set control block. A data set 
label for a data set in direct access 
storage. 

data space. A storage area defined in 
the volume table of contents of a 
direct-access volume for the exclusive 


use of VSAM to store data sets, indexes, 
and catalogs. 

direct access. The retrieval or storage 
of data by a reference to its location 
in a data set rather than relative to 
the previously retrieved or stored data. 
( See also addressed direct access and 
keyed direct access.) 

DSOB. C See data set control block.) 

dynamic allocation. The allocation of a 
data set or volume by the use of the 
data set name or volume serial number 
rather than by the use of information 
contained in a JCL statement. 

entry. A collection of information 
about a cataloged object in a VSAM 
master or user catalog. Each entry 
resides in one or more 512-byte record. 

entry name. A unique name for each 
component or object as it is identified 
in a catalog. The entryname is the same 
as the dsname in a DD statement that 
describes the object. 

entry sequence. The order in which data 
records are physically arranged 
(according to ascending RBA) in 
auxiliary storage, without respect to 
their contents. ( Contrast with key.) 

entry-sequenced data set. A data set 
whose records are loaded without respect 
to their contents, and whose RBAs cannot 
change. Records are retrieved and 
stored by addressed access, and new 
records are added at the end of the data 
set. 

esoteric name. An arbitrary name 
provided by the user to identify a group 
of devices having similar 
characteristics (for example, DISK, 

TAPE, SYSDA). 

extent. A continuous space allocated on 
a direct-access storage volume, reserved 
for a particular data space or data set. 
An extent of a data set contains a whole 
number of control areas. 

field. In a record or a control block, 
a specified area used for a particular 
category of data or control information. 

GDG. ( See generation data group base 
entry.) 

CDS. ( See generation data set.) 

generation data group base entry. An 
entry that permits non-VSAM data sets to 
be associated with other non-VSAM data 
sets as generation data sets. 

generation data set. One of a 
collection of historically related 
non-VSAM data sets; the collection of 
these data sets is known as a generation 
data group. 
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index* As used in this publication, an 
ordered collection of pairs, each 
consisting of a key and a pointer, used 
by VSAM to sequence and locate the 
records of a key-sequenced data set; 
organized in levels of index records. 
( See also index level, index set, and 
sequence set.) 

index component* That part of a 
key-sequenced data set, catalog, or 
alternate index, that establishes the 
sequence of the data records within the 
object it indexes. The index is used to 
locate each record in the object's data 
component, based on the record's key 
value. 

index entry. A catalog entry that 
describes the index component of a 
key-sequenced cluster, alternate index, 
or catalog. An index entry contains the 
index component's attributes, passwords 
and protection attributes, allocation 
and extent information, and statistics. 

index level. A set of index records 
that order and give the location of 
records in the next lower level or of 
control intervals in the data set that 
it controls. 

index record. A collection of index 
entries that are retrieved and stored as 
a group. ( Contrast with data record.) 

index set. The set of index levels 
above the sequence set. The index set 
and the sequence set together comprise 
the index. 

integrity. ( See data integrity.) 

key. One or more characters within an 
item of data that are used to identify 
it or control its use. As used in this 
publication, one or more consecutive 
characters taken from a data record, 
used to identify the record and 
establish its order with respect to 
other records. 

key-sequenced data set. A data set 
whose records are loaded in key sequence 
and controlled by an index. Records are 
retrieved and stored by keyed access or 
by addressed access, and new records are 
inserted in the data set in key sequence 
by means of distributed free space. 
Relative byte addresses of records can 
change. 

master catalog. A key-sequenced data 
set with an index containing extensive 
data-set and volume information that 
VSAM requires to locate data sets, to 
allocate and deallocate storage space, 
to verify the authorization of a program 
or operator to gain access to a data 
set, and to accumulate usage statistics 
for data sets. 

non-VSAM entry. A catalog entry that 
describes a non-VSAM data set. A 


non-VSAM entry contains the data set's 
volume serial number and device type. 

If the data set resides on a magnetic 
tape volume, the entry can also identify 
the data set's file number. When the 
data set resides on a direct-access 
device, the operating system obtains 
further information by examining the 
data set's DSCB (data set control block) 
in the volume's VTOC (volume table of 
contents). 

object. A logical entity created by 
VSAM, such as a cluster (VSAM data set) 
and its components, an alternate index 
and its components, a VSAM catalog and 
its components, a path, or a VSAM data 
space. 

page space. A VS2 system data set. A 
page space is cataloged as an 
entry-sequenced cluster (that is, the 
page space entry is similar to a cluster 
entry, and it points to a data entry). 

password. A unique string of characters 
stored in a catalog that a program or a 
computer operator at the console must 
supply to meet security requirements 
before the program gains access to a 
data set. 

path. A data set name for the 
combination of an alternate index and 
its base cluster, or an alias for a VSAM 
data set. 

path entry. A catalog entry that 
contains information about a path, and 
that points to the path's related 
objects. 

plaintext. A data set or key which is 
not enciphered (with the cryptographic 
option). A data set or key is plaintext 
before it is enciphered and after it is 
deciphered. 

portability. The ability to use VSAM 
data sets with different operating 
systems. Volumes whose data sets are 
cataloged in a user catalog can be 
demounted from storage devices of one 
system, moved to another system, and 
mounted on storage devices of that 
system. Individual data sets can be 
transported between operating systems 
using access method services. 

primary space allocation. Initially 
allocated space on a direct-access 
storage device, occupied by or reserved 
for a particular data set. ( See also 
secondary space allocation.) 

prime index. The index component of a 
key-sequenced data set. ( See also index 
and alternate index.) 

prime key. ( See key.) 

qualified name. A name that is 
segmented by periods; each name segment 
is referred to as a qualifier. 
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RBA. ( See relative byte address.) 

record. ( See index record, data record, 
stored record.) 

recoverable catalog. A catalog defined 
with the recoverable attribute. 

Duplicate catalog entries are put into 
CRAs that can be used to recover data in 
the event of catalog failure. ( See also 
CRA.) 

recovery volume. The first volume of a 
prime index, if the VSAM data set is a 
key-sequenced cluster; otherwise, the 
first volume of the data set, if 
entry-sequenced. 

relative byte address. The displacement 
of a data record or a control interval 
from the beginning of the data set to 
which it belongs; independent of the 
manner in which the data set is stored. 

secondary space allocation. A 
contiguous space on a direct-access 
device, occupied by or reserved for a 
particular data set, which is allocated 
after space in the primary extent has 
been exhausted. ( See also primary space 
allocation.) 

security. ( See data security.) 

sequence set. The lowest level of the 
index of a key-sequenced data set; it 
gives the locations of the control 
intervals in the data set and orders 
them by the key sequence of the data 
records they contain. The sequence set 
and the index set together comprise the 
index. 

spanned record. A logical record whose 
length exceeds control interval length, 
and crosses (or spans) one or more 


control interval boundaries within a 
control area. 

sphere record. A collection of 
logically related subrecords in one VSAM 
logical record. 

step catalog. ( See job catalog.) 

stored record. A data record, together 
with its control information, as stored 
in auxiliary storage. 

subrecord. The user definition level of 
a sphere, such as an AIX, cluster, or 
generation data set. 

user catalog. A catalog used in the 
same way as the master catalog, but 
optional and pointed to by the master 
catalog, and also used to lessen the 
contention for the master catalog and to 
facilitate volume portability. 

user catalog connector. ( See catalog 
connector.) Interval in the data set 
controlled by the index. 

volume cleanup. The process of deleting 
all VSAM data spaces from a volume and 
removing a VSAM catalog f s ownership of 
the volume, even though the volume 
contains VSAM data records. 

volume entry. A catalog entry that 
describes a volume owned by the catalog. 
All VSAM data spaces on the volume are 
described in the volume entry, and the 
catalog is no longer available. 

volume table of contents. A table on a 
direct access volume that describes each 
data set on the volume. 

VT0C. ( See volume table of contents.) 



V 
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C3 


abbreviations 

TSO restrictions 13 
abort a job 10 
access 

read only 

in EXPORT command 175 
access method services 
coding commands 3 

continuing commands 7 
parameters 3 
password 5 
structure 3 
subparameters 4, 5 
function 12 
functional commands 29 
summary 1, 326 
invoking 319 

TSO terminal 13 
ADDVQLUMES parameter 
in ALTER command 34 
ALIAS parameter 

in DEFINE command 60 
in DELETE command 154 
in LISTCAT command 206 
aliasname subparameter 
coding 5 
ALL parameter 

in LISTCAT command 210 
output listing 284 
ALL subparameter 
in EXPORTRA 180 
in RESETCAT command 247 
ALLOCATION parameter 

in LISTCAT command 210 
output listing 292 
allocation, space 
direct 11 
dynamic 8 
JCL DD statement 9 
alphabetic characters 6 
alphameric characters 6 
ALTER command 

entry types that can be altered 31 
examples 47 
format 31 

order of catalog search 15 
parameters 

optional 34 
required 34 
alternate index 

building CBLDINDEX) 49 
creating 

example 83 
defining 64 
deleting 154 
exporting 174 
importing 189 
path 130 
record size 75 
alternate key 73 
alternate name 
deleting 154 
alternate target data set 
identification 


JCL DD statement 10 
ALTERNATEINDEX parameter 
in DELETE command 154 
in LISTCAT command 206 
ALTERNATEINDEX subcommand 
in DEFINE command 64 
AMSDUMP DD statement 10 
APF (authorized program facility) 
authorization 319 
AREAS parameter 

in PARM command 24 
argument lists 

referenced by invoking macros 
ATTACH macro 14, 319 
ATTEMPTS parameter 

in ALTER command 34 
in DEFINE command 

ALTERNATEINDEX 67 
CLUSTER 90 
PAGESPACE 123 
PATH 131 
USERCATALOG 142 
note to TSO users 35 
attributes 

nullifying 39 
AUTHORIZATION parameter 
in ALTER command 35 
NULLIFY 40 
in DEFINE command 

ALTERNATEINDEX 67 
CLUSTER 90 
PAGESPACE 124 
PATH 131 
USERCATALOG 142 
authorized program facility 
See APF 

Auxiliary Storage Management 126 


B 


BIND parameter 

in ALTER command 44 
in DEFINE command 

ALTERNATEINDEX 79 
CLUSTER 104 
binding 

MSS (Mass Storage System) 20 
blanks 

separators 3 
BLDINDEX command 
example 52 
format 49 

order of catalog selection 15 
parameters 

optional 50 
required 49 

buffer 

altering size 35 
buffering 

VSAM data sets 9 
BUFFERSPACE parameter 
in ALTER command 35 
in DEFINE command 

ALTERNATEINDEX 67 
CLUSTER 90 


319 
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USERCATALOG 142 
building an alternate index 49 




CALL macro 14, 320 
CANDIDATE parameter 
in DEFINE command 
SPACE 136 
CATALOG parameter 

in ALTER command 35 
in BLDINDEX command 50 
in CNVTCAT command 57 
in DEFINE command 
ALIAS 60 

ALTERNATEINDEX 68 
CLUSTER 91 

GENERATIONDATAGROUP 114 
NONVSAM 119 
PAGESPACE 123 
PATH 131 
SPACE 138 
USERCATALOG 142 
in DELETE command 156 
in IMPORT command 191 
in IMPORT CONNECT command 186 
in IMPORTRA command 199 
in LISTCAT command 207 
in LISTCRA command 213 
in RESETCAT command 247 
catalog recovery 
example 203 

catalog recovery space 144 
catalogs 

connecting to master catalog 
in IMPORT command 186 
defining 140 
deleting entries 154 
listing entries 205 
CHAIN parameter 

in PARM command 25 
CHARACTER parameter 

in PRINT command 218 
CHECKID parameter 

in CHKLIST command 53 
checkpoint data set 53 
CHKLIST command 
examples 55 
format 53 

listing tape volumes mounted at 
checkpoint 53 
parameters 

optional 53 
required 53 
sample output 315 
CIPHERUNIT parameter 
in REPRO command 
ENCIPHER 231 
cluster 

creating 87 
defining 87 
deleting 154 
exporting 174 
importing 189 

listing its catalog entry 206 
path 130 

printing its contents 217 
verifying its end-of-file values 254 
CLUSTER parameter 

in DELETE command 154 
in LISTCAT command 206 


CLUSTER subcommand 

in DEFINE command 87 
CNVTCAT command 
examples 58 
format 56 

order of catalog selection 16 
parameters 

optional 57 
required 56 
CODE parameter 

in ALTER command 36 
NULLIFY 40 
in DEFINE command 

ALTERNATEINDEX 68 
CLUSTER 91 
PAGESPACE 124 
PATH 132 
USERCATALOG 143 
CODE subparameter 
coding 5 
coding 

access method services commands 3 
aliasname subparameter 5 
alphameric characters 6 
CODE subparameter 5 
continuing commands 4, 7 
control commands 

continuation errors 26 
entryname subparameter 5 
entrypoint subparameter 6 
keyword parameter 3 
national characters 6 
NEWNAME subparameter 6 
ownerid subparameter 6 
parameters 7 
parentheses 4 
password 5 

PASSWORD subparameter 6 
pdsname(membername) subparameter 6 
positional parameter 3 
special character 5, 6 
string subparameter 6 
subparameters 5 
terminator 8 
volser subparameter 6 
command execution, controlling 21 
commands, access method services 
ALTER 31 
BLDINDEX 49 
CHKLIST 53 
CNVTCAT 56 
DEFINE 

ALIAS 60 

ALTERNATEINDEX 62 
CLUSTER 85 

GENERATIONDATAGROUP 114 
MASTERCATALOG 140 
NONVSAM 118 
PAGESPACE 122 
PATH 130 
SPACE 136 
USERCATALOG 140 
DELETE 153 
EXPORT 174 

EXPORT DISCONNECT 172 
EXPORTRA 179 
IMPORT 189 
IMPORT CONNECT 186 
IMPORTRA 199 
LISTCAT 205 
LISTCRA 213 
PRINT 217 
REPRO 226 
RESETCAT 247 
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summary 1/ 326 
VERIFY 254 
commas 

separators 3 
comments 

coding 3 
COMPARE parameter 

in LISTCRA command 213, 214 
LISTCRA command 

output listing 312 
components 

in DEFINE command 
USERCATALOG 146 
concatenated DD statement 
defining a cluster 93 
FILE parameter 37 
condition codes 21 

controlling command execution 21 
processor 323 
CONNECT subcommand 

in IMPORT command 186 
connecting a user catalog 
in IMPORT command 186 
continuation mark 
hyphen 7 
plus sign 4 
continuing commands 
coding 7 
control area 

preformatting 

alternate index 78 
cluster 103 
control commands 

continuation errors 26 
control interval 

crossing boundaries 102 
control volume pointer entry 
See CVPE 

CONTROLINTERVALSIZE parameter 
in DEFINE command 

ALTERNATEINDEX 68 
CLUSTER 91 

controlling command execution 21 
condition codes 21 
examples 27 
null commands 23 
C0NTR0LPW parameter 

in ALTER command 36 
NULLIFY 40 
in DEFINE command 

ALTERNATEINDEX 69 
CLUSTER 92 
PAGESPACE 124 
PATH 132 
USERCATALOG 143 
converting a catalog 56 
copying 

a data set 226 
a SAM data set 227 
catalog 

examples 236 
ISAM records 227 

copying catalogs for device conversion, 
example 239 
COUNT parameter 

in PRINT command 221 
in REPRO command 231 
CRA parameter 

in EXPORTRA command 179 
CRAFILES parameter 

in RESETCAT command 247 
CRAVOLUMES parameter 

in RESETCAT command 247 
CREATION parameter 


in LISTCAT command 207 
output listing 297 
cross-region sharing 
alternate index 76 
in ALTER command 42 
in DEFINE CLUSTER command 100 
cross-system sharing 
alternate index 77 
in ALTER command 43 
in DEFINE CLUSTER 101 
cryptographic option 

access method services 
parameters 231 
examples 242, 246 
CV0LEQUATES parameter 

in CNVTCAT command 57 
CVPE (control volume pointer entry) 57 
CYLINDERFAULT parameter 
in ALTER command 44 
in DEFINE command 
ALTERNATEINDEX 79 
CLUSTER 104 
CYLINDERS parameter 
in DEFINE command 
ALTERNATEINDEX 64 
CLUSTER 87 
PAGESPACE 122 
SPACE 137 
USERCATALOG 141 




data component 

alternate index 63, 82 
cluster 86, 105 

control interval size 91 
record size 98 
user catalog 146 
data encrypting key 

cryptographic option 231 
establishing 232 
data integrity 

sharing data sets 
cluster 100 

in DEFINE ALTERNATEINDEX 
command 76 
data organization 
specifying 95 
DATA parameter 

in LISTCAT command 206 
data set 

creating 87 
defining 

example 106 
identification 8 
organization 95 
protection 9 
sharing 

cluster 100 
in ALTER command 42 
in DEFINE ALTERNATEINDEX 
command 76 
unique 80, 104 
data set type 

specifying 95 
data space 

allocating 136 
defining 136 
examples 139 
extending 137 
recovery area 122 
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suballocation 

alternate index 80 
DATAKEYFILE parameter 
in REPRO command 
DECIPHER 234 
ENCIPHER 232 
DATAKEYVALUE parameter 
in REPRO command 
DECIPHER 234 
ENCIPHER 232 
DATASET parameter 

in VERIFY command 254 
DATATEST parameter 

in EXAMINE command 170 
debugging tool 
TRACE 24 

DECIPHER parameter 
in REPRO 

examples 244 
in REPRO command 234 
DEFINE command 
ALIAS 

examples 61 
format 60 

optional parameter 60 
required parameters 60 
ALTERNATEINDEX 

data component 63 
example 83 
format 62 
index component 63 
optional parameter 67 
required parameters 64 
CLUSTER 

data component 86 
data organization 95 
example 106 
format 85 
index component 86 
optional parameters 90 
required parameters 87 
GENERATIONDATAGRGUP 
format 114 

optional parameters 114 
required parameters 114 
MASTERCATALOG 

required parameters 140 
NONVSAM 

format 118 

optional parameters 119 
required parameters 118 
order of catalog selection 16 
PAGESPACE 

examples 128 
format 122 

optional parameters 123 
required parameters 122 
PATH 

examples 135 
format 130 

optional parameters 131 
required parameters 130 
SPACE 

examples 139 
format 136 

optional parameters 138 
required parameters 136 
USERCATALOG 

components 146 
example 147 
format 140 

optional parameters 142 
required parameters 140 
defining a cluster 85 


defining a data space 136 
defining a generation data group 114 
defining a non-VSAM data set 118 
defining a page space 122 
defining a path 130 
defining a user catalog 140 
example 147 
defining an alias 60 
defining an alternate entryname 60 
defining an alternate index 62 
alternate index 62 
DELETE command 

catalog cleanup 164 
example 161 
format 153 

optional parameters 154 
order of catalog search 17 
required parameters 153 
deleting 

catalog entries 154 
examples 161 
delimiter 

in PRINT command 219 
in REPRO command 227, 230 
DESTAGEWAIT parameter 
in ALTER command 36 
in DEFINE command 

ALTERNATEINDEX 69 
CLUSTER 92 
USERCATALOG 143 
destaging 36 

MSS (Mass Storage System) 19 
DEVICETYPES parameter 
in DEFINE command 
NONVSAM 118 

in IMPORT CONNECT command 186 
in IMPORTRA command 200 
direct allocation 11 
DISCONNECT subcommand 

in EXPORT command 172 
disconnecting a user catalog 
in EXPORT command 172 
DO command 21, 23 
DO-END command sequence 21, 23 
dummy records 
copying 227 

DUMP COMPARE output listing 
LISTCRA command 313 
DUMP output listing 

LISTCRA command 308 
DUMP parameter 

in LISTCRA command 214 
in PRINT command 218 
dynamic allocation 8 




ELSE parameter 21 
in IF command 23 
EMPTY parameter 

in ALTER command 36 
in DEFINE command 

GENERATIQNDATAGROUP 115 
ENCIPHER parameter 

in REPRO command 231 
examples 242 
END command 21, 23 
ENTRIES parameter 

in EXPORTRA command 180 
in LISTCAT command 208 
entry-sequenced data set 95 
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defining 

example 110 
exporting 

example 178 
importing 

example 198 
entryname subparameter 
coding 5 

entrypoint subparameter 
coding 6 

ENVIRONMENT parameter 
in REPRO command 227 
ERASE parameter 

in ALTER command 37 
in DEFINE command 
ALTERNATEINDEX 70 
CLUSTER 93 

in DELETE command 157 
in EXPORT command 175 
in IMPORT command 191 
ERRQRLIMIT parameter 

in EXAMINE command 170 
esoteric name 118 
EXAMINE command 
format 169 

optional parameters 170 
required parameters 169 
examples 

controlling command execution 27 
exception 

I/O error 37 
EXCEPTIONEXIT parameter 
in ALTER command 37 
in ALTER command (NULLIFY) 40 
in DEFINE command 

ALTERNATEINDEX 70 
CLUSTER 93 
EXEC statement 12 
EXPIRATION parameter 

in LISTCAT command 209 
output listing 297 
EXPORT command 
examples 177 
format 174 

optional parameters 175 
required parameters 174 
EXPORT DISCONNECT command 
example 173 
format 172 

required parameters 172 
exporting 

VSAM recoverable catalogs 179 
EXPORTRA command 
examples 182 
format 179 

optional parameters 181 
required parameters 179 
external file key 

cryptographic option 231 
EXTERNALKEYNAME parameter 
in REPRO command 
ENCIPHER 231 
EXTERNALSORT parameter 
in BLDINDEX command 51 


m 


FILE parameter 

in ALTER command 37 
in DEFINE command 

ALTERNATEINDEX 70 
CLUSTER 93 
PAGESPACE 124 
PATH 132 
SPACE 138 
USERCATALOG 143 
in DELETE command 157 
in IMPORT command 192 
in IMP0RTRA command 201 
in VERIFY command 254 
FILESEQUENCENUMBERS parameter 
in DEFINE command 
N0NVSAM 120 

fixed-length records 99 
FOR parameter 

in ALTER command 44 
in DEFINE command 
ALTERNATEINDEX 79 
CLUSTER 104 

GENERATIONDATAGROUP 116 
N0NVSAM 120 
PAGESPACE 126 
PATH 133 
USERCATALOG 145 
FORCE parameter 

in DELETE command 158 
in EXPORTRA command 181 
FREESPACE parameter 

in ALTER command 37 
in DEFINE command 

ALTERNATEINDEX 71 
CLUSTER 94 
FROMADDRESS parameter 
in PRINT command 219 
in REPRO command 228 
FROMKEY parameter 

in PRINT command 219 
in REPRO command 228 
FROMNUMBER parameter 

in PRINT command 220 
in RfcPRQ command 228 
FULL parameter 

in FARM command 25 
functional commands 
summary 1, 29 


DD 

generation data group 
altering attributes 
example 48 
creating 114 
defining 

example 116 
generation data set 

cataloging maximum number 36 
uncatalogina 42 
GENERATIONDATAGROUP parameter 
in DELETE command 155 
in LISTCAT command 206 
GENERATIONDATAGROUP subcommand 
in DEFINE command 114 
generic key 

specified in PRINT command 219 
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generic name 
altering 

example 47 
device type 118 
global resource serialization 
See GRS 
glossary 343 
GRAPHICS parameter 

in PARM command 25 
GRS (global resource serialization) 

multiple system sharing 42/ 76/ 101 



HEX parameter 

in PRINT command 218 
high key 

alternate index 72 
cluster 96 
HISTORY parameter 

in LISTCAT command 209 
output listing 295 

hyphen 

continuation mark 7 



I/O routines 

user controlled 323 
IDCAMS program 12/ 321 
identifying tape volumes 
CHKLST command 53 
IF command 21/ 22 

IF-THEN-ELSE command sequence 21/ 22 
null commands 23 
IGNORE parameter 

in RESETCAT command 248 
IMBED parameter 

in DEFINE command 

ALTERNATEINDEX 71 
CLUSTER 94 
IMPORT command 


format 

189 


optional 

parameters 

191 

required 

parameters 

189 

IMPORT CONNECT command 


example 

188 


format 

186 


optional 

parameters 

186 

required 

parameters 

186 


importing recoverable catalogs 199 
IMPORTRA command 
format 199 

optional parameters 199 
required parameters 199 
INDATASET parameter 

in BLDINDEX command 49 
in IMPORT command 189 
in IMPORTRA command 199 
in PRINT command 217 
in REPRO command 226 
index component 

alternate index 63/ 82 
cluster 86/ 105 
key-sequenced cluster 

control interval size 92 
user catalog 146 
INDEX parameter 


in LISTCAT command 
INDEXED parameter 
in DEFINE command 
CLUSTER 95 
INDEXTEST parameter 
in EXAMINE command 
INFILE parameter 

in BLDINDEX command 49 
in CHKLIST command 53 
in CNVTCAT command 56 
in EXPORT command 175 
in EXPORTRA command 180 
in IMPORT command 189 
in IMPORTRA command 199 
in LISTCRA command 213 
in PRINT command 217 
in REPRO command 226 
INHIBIT parameter 

in ALTER command 38 
INHIBITSOURCE parameter 
in EXPORT command 175 
INHIBITTARGET parameter 
in EXPORT command 176 
internal file key 

cryptographic option 231 
INTERNALKEYNAME parameter 
in REPRO command 
ENCIPHER 231 
INTERNALSORT parameter 

in BLDINDEX command 51 
INTOEMPTY parameter 

in IMPORT command 192 
invoking access method services 12 
from problem program 319 
PL/I program 321 
invoking macro instructions 319 


206 

w 

169 
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JCL (job control language) 
for LISTCAT jobs 276 
for LISTCRA jobs 303 
JCL DD parameter 
cautions 316 
JCL DD statement 9 

invoking access method services 12 
JOB statement 12 
JOBCAT DD statement 12 

allocating user catalogs 11 



key 

cryptographic option 231 
key field 

alternate index 73 
key sequenced data set 
defining 

example 108/ 111 
key value 

alternate index 80 
key-sequenced data set 95 
exporting 

example 177 ^ 

importing M 

example 197 4 / 

KEYRANGES parameter 
in DEFINE command 
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ALTERNATEINDEX 72 
CLUSTER 96 

in IMPORT command 192 
KEYS parameter 

in ALTER command 38 
in DEFINE command 

ALTERNATEINDEX 73 
CLUSTER 97 
keyword parameter 
coding 3 
keywords 

LISTCAT output 256 




LASTCC condition code 
using 323 
LASTCC parameter 

in IF command 22 
in SET command 24 
length 

alternate key 73 
LEVEL parameter 

in LISTCAT command 208 
LIMIT parameter 

in DEFINE command 

GENERATIONDATAGROUP 114 
LINK macro 14, 319 
LIST parameter 

in CNVTCAT command 57 
LISTCAT command 
examples 211 
format 205 
in TSO environment 
examples 299 

interpreting listings 256 
optional parameters 205 
order of catalog search 18 
output keywords 256 
LISTCRA command 
format 213 

interpreting listings 301 
optional parameters 213 
required parameters 213 
listing catalog entries 205 
listing recoverable catalogs 213 
LOAD macro 14, 320 
low key 

alternate index 72 
cluster 96 


H 


macros 


ATTACH 319 

CALL 

320 

LINK 

319 

LOAD 

320 

margins 


coding 3 

MARGINS 

parameter 


in PARM command 25 
Mass Storage System 
See MSS 

MASTERCATALOG parameter 
in CNVTCAT command 58 
MASTERCATALOG subcommand 
in DEFINE command 140 


MASTERPN parameter 

in ALTER command 39 
NULLIFY 40 
in DEFINE command 
ALTERNATEINDEX 73 
CLUSTER 97 
PAGESPACE 125 
PATH 132 
USERCATALOG 143 
in EXPORTRA command 181 
in LISTCRA command 214 
in RESETCAT command 248 
MAXCC parameter 

in IF command 22 
in SET command 24 
maximum condition code 22 
modal command 

PARM command 26 
TSO restrictions 14 
model 

using to define cluster 
example 112 
MODEL parameter 
example 150 
in DEFINE command 

ALTERNATEINDEX 73 
CLUSTER 97 
PAGESPACE 125 
PATH 132 
USERCATALOG 144 
MODULE parameter 
in ALTER command 
NULLIFY 40 

MSS (Mass Storage System) 
restrictions 19 
multiple system sharing 
GRS (global resource 
serialization) 42, 76, 101 




NAME parameter 

in DEFINE command 
ALIAS 60 

ALTERNATEINDEX 64 
CLUSTER 87 

GENERATIONDATAGROUP 114 
NONVSAM 118 
PAGESPACE 122 
PATH 130 
USERCATALOG 141 
in EXAMINE command 169 
in LISTCAT command 209 
in LISTCRA command 214 
national characters 7 
NENNAME parameter 

in ALTER command 39 
in IMPORT command 193 
NENNAME subparameter 
coding 6 

NOCOMPARE parameter 

in LISTCRA command 214 
NODATATEST parameter 

in EXAMINE command 170 
NODESTAGENAIT parameter 
in ALTER command 36 
in DEFINE command 

ALTERNATEINDEX 69 
CLUSTER 93 
USERCATALOG 143 
NOEMPTY parameter 
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